API đối tác

Tích hợp trình xem trước biểu ngữ X của bạn

Trong trình tạo Biểu ngữ X của CitrusAd, chúng tôi cung cấp trình xem trước cho nhà bán lẻ và nhà quảng cáo, cho phép:

  • Nhà quảng cáo xem trước giao diện biểu ngữ trước khi khởi chạy chiến dịch
  • Nhà quảng cáo xem biểu ngữ trong trình quản lý chiến dịch
  • Nhà bán lẻ xem lại biểu ngữ trước khi chấp thuận cho biểu ngữ xuất hiện trên trang web.

Đối với bất kỳ nhà bán lẻ nào muốn tùy chỉnh hiển thị biểu ngữ x, bạn có thể tích hợp trình xem trước biểu ngữ của mình vào nền tảng của CitrusAd thông qua trình xem trước được lưu trữ trên trang web của bạn mà CitrusAd đặt trong khung cửa sổ.

🚧

Đây là nhà bán lẻ được lưu trữ

Là nhà bán lẻ, bạn sẽ cần lưu trữ nội dung này trên url hoặc liên kết bạn sở hữu và quản lý.

Việc này giúp bạn hoàn toàn chủ động trong việc quản lý và cập nhật trang này khi trang web hay thiết kế trang web của bạn thay đổi - tức là bạn sẽ không phải phụ thuộc vào CitrusAd khi muốn thay đổi gì đó.

Nói chung, chúng tôi khuyên bạn nên lưu trữ nội dung này trên trang web của mình tại một URL ẩn, ví dụ như store.com/banner-previewer, nhưng bạn có quyền quyết định nơi nội dung được lưu trữ.

Bạn cũng có thể tùy ý cập nhật cách hiển thị hình ảnh và văn bản mà CitrusAd cung cấp trên trang web đang hoạt động. Mọi thay đổi đối với biểu ngữ trên trang web đang hoạt động sẽ được phản ánh ngay tức thì trên nền tảng CitrusAd thông qua trình xem trước bên ngoài.

1200

Hình ảnh trình xem trước bên ngoài

Cách tích hợp quy cách xem trước

Để hiển thị nội dung được CitrusAd chuyển đến trình xem trước bên ngoài của bạn, bạn sẽ cần lưu trữ trình xem trước biểu ngữ tách riêng của mình trên một trang riêng biệt do nhà bán lẻ sở hữu và quản lý. Chúng tôi đề nghị https://www.<retailer.com>/banner-preview/bannerx.

Bên dưới là quy cách OpenAPI3:

openapi: "3.0.0"
info:
  version: 0.0.1
  title: BannerX Preview
  license:
    name: MIT
paths:
  '/banner-preview':
    get:
      summary: Render a preview of a bannerX
      operationId: getBannerXPreview
      tags:
        - campaign
      parameters:
        - name: "contentStandardId"
          in: query
          description: Content Standard ID to use for rendering. Can be ignored for external previewers if only 1 content standard is available.
          examples:
            uat:
              value: "bd59be89-b13f-440f-a57e-0e5a481bec8b"
              summary: "example UAT content standard ID"
          required: true
          schema:
            type: string
        - name: "slotId"
          in: query
          description: Slot ID defined within the content standard to use for rendering. Can be ignored for external previewers if only 1 slot is available.
          examples:
            uat:
              value: "left_ribbon"
              summary: "slot ID"
          required: true
          schema:
            type: string
        - name: "slotType"
          in: query
          description: Banner slot type to use for rendering. Can be ignored for external previewers if only 1 slot type is available.
          examples:
            uat:
              value: "DOUBLE_TILE"
              summary: "banner slot type"
          required: true
          schema:
            type: string
            enum:
              - UNDEFINED
              - BANNER
              - SINGLE_TILE
              - DOUBLE_TILE
        - name: "headingText"
          in: query
          description: Heading text to insert into the banner rendering.
          examples:
            uat:
              value: "Juicy apples!"
              summary: "banner heading text"
          required: false
          schema:
            type: string
        - name: "bannerText"
          in: query
          description: Banner text to insert into the banner rendering.
          required: false
          examples:
            uat:
              value: "Citrus UAT Banner"
              summary: "banner text"
          schema:
            type: string
        - name: "bannerTextColour"
          in: query
          description: Banner text colour in RGB HEX format.
          examples:
            uat:
              value: "000000"
              summary: "banner text colour"
          required: false
          schema:
            type: string
        - name: "ctaEnabled"
          in: query
          description: Flag to designate that CTA button should be rendered.
          examples:
            uat:
              value: true
              summary: "banner CTA enabled flag"
          required: false
          schema:
            type: boolean
        - name: "ctaLink"
          in: query
          description: Link for Call-To-Action element.
          examples:
            uat:
              value: "https://www.retailer.com/promo/6ru0GM5"
              summary: "banner CTA link"
          required: false
          schema:
            type: string
        - name: "backgroundColour"
          in: query
          description: Banner text colour in RGB HEX format.
          examples:
            uat:
              value: "000000"
              summary: "banner background colour"
          required: false
          schema:
            type: string
        - name: "backgroundImage"
          in: query
          description: Background image URL to render in the banner.
          examples:
            uat:
              value: "https://cdn.flavedo.io/s/7b965e85-64ae-4574-9d6d-4c45c448668e"
              summary: "background image URL"
          required: false
          schema:
            type: string
        - name: "backgroundImagePosition"
          in: query
          description: Background image position.
          examples:
            uat:
              value: "TOP_ALIGNED"
              summary: "background image position"
          required: false
          schema:
            type: string
            enum:
              - UNDEFINED
              - FILL
              - REPEATING
              - LEFT_ALIGNED
              - RIGHT_ALIGNED
              - TOP_ALIGNED
              - BOTTOM_ALIGNED
        - name: "secondaryBackgroundImage"
          in: query
          description: Secondary background image URL to render in the banner.
          examples:
            uat:
              value: "https://cdn.flavedo.io/s/7b965e85-64ae-4574-9d6d-4c45c448668e"
              summary: "secondary background image URL"
          required: false
          schema:
            type: string
        - name: "secondaryBackgroundImagePosition"
          in: query
          description: Secondary background image position.
          examples:
            uat:
              value: "TOP_ALIGNED"
              summary: "secondary background image position"
          required: false
          schema:
            type: string
            enum:
              - UNDEFINED
              - FILL
              - REPEATING
              - LEFT_ALIGNED
              - RIGHT_ALIGNED
              - TOP_ALIGNED
              - BOTTOM_ALIGNED
        - name: "heroImage"
          in: query
          description: Primary hero image URL.
          examples:
            uat:
              value: "https://cdn.flavedo.io/s/7b965e85-64ae-4574-9d6d-4c45c448668e"
              summary: "primary hero image URL"
          required: false
          schema:
            type: string
        - name: "heroImageAltText"
          in: query
          description: Primary hero image alt text.
          examples:
            uat:
              value: "New flavour chips"
              summary: "hero image alt text"
          required: false
          schema:
            type: string
        - name: "secondaryHeroImage"
          in: query
          description: Secondary hero image URL.
          examples:
            uat:
              value: "https://cdn.flavedo.io/s/02c1440c-bad4-4cf8-a208-be910827e30a"
              summary: "secondary hero image URL"
          required: false
          schema:
            type: string
        - name: "secondaryHeroImageAltText"
          in: query
          description: Secondary hero image alt text.
          examples:
            uat:
              value: "New flavour sauce"
              summary: "secondary hero image alt text"
          required: false
          schema:
            type: string
        - name: "secondaryHeroMode"
          in: query
          description: Secondary hero image display mode.
          examples:
            uat:
              value: "BLOCK"
              summary: "secondary hero image mode"
          required: false
          schema:
            type: string
            enum:
              - UNDEFINED
              - BLOCK
              - LANDSCAPE
        - name: "gtins"
          in: query
          description: |
            List of a subset of GTINs attached to the campaign.
            Please note that this parameter is marked VOLATILE and may change or be deprecated in the future.
            While we will inform prior to any changes to the API surface,
            anyone relying on this parameter should be aware of it's volatility.
          examples:
            uat:
              value: [ "7913494","6815686" ]
              summary: "gtin list"
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
      responses:
        '200':
          description: OK response
        '400':
          description: Bad request error response
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    description: Error message.
        '404':
          description: Not found error response
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    description: Error message.
        '500':
          description: Internal server error response
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    description: Error message.

🚧

API biểu ngữ X phải có khả năng phản hồi biểu ngữ.

📘

Quy cách này có thể thay đổi - nhà cung cấp dịch vụ tích hợp sẽ được thông báo về mọi thay đổi trước khi triển khai.

Khi người dùng tải trình xem trước trên nền tảng CitrusAd, yêu cầu LẤY sẽ được gửi cùng với một tập hợp các tham số đã xác định được hiển thị trên trình xem trước. Sau đó, yêu cầu được đặt trong khung nội tuyến trên nền tảng CitrusAd.

Yêu cầu sẽ giống như ví dụ dưới đây: 

https://www.[YOUR_RETAILER_SITE]/bannerx?contentStandardId=bd59be89-b13f-440f-a57e-0e5a481bec8b&slotId=Search_in_grid_1&slotType=DoubleTile&headingText=Milk&bannerText=Milk&bannerTextColour=ecdfdf&backgroundColour=d55525&backgroundImagePosition=topaligned&secondaryBackgroundImagePosition=topaligned&heroImage=https%3A%2F%2Fstorage.googleapis.com%2Fcitrus-banner-images-pending-australia-southeast1%2Fstaging%2F74fc5966-8d8d-487e-b2a9-45f994957815&heroImageAltText=test&secondaryHeroImage=https%3A%2F%2Fstorage.googleapis.com%2Fcitrus-banner-images-pending-australia-southeast1%2Fstaging%2F2bfd0dcb-27d5-4469-a53d-c1681f675c6e&secondaryHeroImageAltText=test&secondaryHeroMode=landscape&gtins=7459770&gtins=59398&gtins=7895365