CitrusAd Banner X 크리에이터는 소매업체 및 광고주에 대한 미리보기를 통해 다음 기능을 제공합니다.

광고주가 캠페인을 시작하기 전에 배너의 모양을 미리 볼 수 있음
광고주가 캠페인 관리자에서 배너를 볼 수 있음
소매업체가 웹사이트에 배너를 게시하는 것을 승인하기 전에 배너를 검토할 수 있음

배너 x의 렌더링을 사용자 지정하려는 소매업체는 해당 사이트에서 호스팅되는 배너 미리보기를 통해 플랫폼 창에 아이프레임을 삽입하여 배너 미리보기를 통합할 수 있습니다.

🚧
이것은 호스팅된 소매업체입니다
소매업체는 자신이 소유하고 관리하는 URL이나 링크에서 이것을 호스팅해야 합니다.
이를 통해 사이트 및 사이트 디자인 변경 시 이를 유연하게 관리하고 업데이트할 수 있으며 플랫폼에 의존하지 않지 않고 독립적으로 조정할 수 있습니다.
일반적으로 retailer.com/banner-previewer와 같은 숨겨진 URL의 사이트에 호스팅하는 것이 좋습니다. 그러나 호스팅 위치는 사용자가 결정해야 합니다.

또한 실시간 사이트에 제공되는 이미지와 텍스트가 렌더링되는 방법을 자유롭게 업데이트할 수 있습니다. 실시간 사이트 내 배너의 모든 변경 사항은 외부 미리보기를 통해 플랫폼에 즉시 반영해야 합니다.

미리보기 사양을 통합하는 방법

CitrusAd 플랫폼을 통해 전달된 콘텐츠를 외부 미리보기로 표시하려면 소매업체가 소유하고 관리하는 별도의 페이지에서 자체 분리된 배너 미리보기를 호스팅해야 합니다. 다음을 권장합니다: https://www.<retailer.com>/banner-preview/bannerx.

OpenAPI3의 스펙은 아래에서 확인할 수 있습니다.

openapi: "3.0.3"
info:
  version: 0.0.2
  title: BannerX Preview
  description: |
    Specification for BannerX preview to be implemented by retailer.

    In our Banner X creator, we offer a previewer for retailers and advertisers which enables:

    - The advertiser to preview their banner’s appearance before launching their campaign
    - The advertiser to view their banner in the campaign manager
    - The retailer to review the banner before approving it to appear on their website.
    - For any retailers wishing to customise the rendering of banner x, you are able to integrate your banner previewer into CitrusAd's platform through a previewer hosted on your site that CitrusAd iframes in the window.

     To display the content passed by our platform to your external previewer, you will need to host your own isolated banner previewer on a separate page owned and managed by the retailer. We suggest https://www.<retailer.com>/banner-preview/bannerx.

paths:
  "/banner-preview/bannerx":
    get:
      summary: Render a preview of BannerX content
      operationId: getBannerXPreview
      tags:
        - retailer
      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:
            content-standard-id:
              value: "bd59be89-b13f-440f-a57e-0e5a481bec8b"
              summary: "example 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:
            slot-id:
              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:
            double-tile-slot-type:
              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:
            banner-heading-text:
              value: "Juicy apples!"
              summary: "banner heading text"
          required: true
          schema:
            type: string
            maxLength: 254
        - name: "bannerText"
          in: query
          description: |
            Banner text to insert into the banner rendering. `<strong>`, `<i>` and `<sup>` tags are supported.
          required: true
          examples:
            banner-text:
              value: "Citrus banner text"
              summary: "banner text"
          schema:
            type: string
            maxLength: 110
        - name: "bannerTextColour"
          in: query
          description: Banner text colour in RGB HEX format.
          examples:
            banner-text-color:
              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:
            cta-enabled:
              value: true
              summary: "banner CTA enabled flag"
          required: false
          schema:
            type: boolean
        - name: "ctaLink"
          in: query
          description: |
            Link for Call-To-Action element. Note: this may be a relative or absolute URL
            depending on the configuration.
          examples:
            cta-link:
              value: "https://www.retailer.com/promo/6ru0GM5"
              summary: "banner CTA link"
          required: false
          schema:
            type: string
            maxLength: 100
        - name: "backgroundColour"
          in: query
          description: Background colour of the rendered banner in RGB HEX format.
          examples:
            banner-background-color:
              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:
            background-image-url:
              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:
            background-image-position:
              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:
            primary-hero-image-url:
              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:
            hero-image-alt-text:
              value: "New flavour chips"
              summary: "hero image alt text"
          required: false
          schema:
            type: string
        - name: "secondaryHeroImage"
          in: query
          description: Secondary hero image URL.
          examples:
            secondary-hero-image-url:
              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:
            secondary-hero-image-alt-text:
              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:
            secondary-hero-image-mode-block:
              value: "BLOCK"
              summary: "secondary hero image mode"
          required: false
          schema:
            type: string
            enum:
              - UNDEFINED
              - BLOCK
              - LANDSCAPE
        - name: "additionalFields"
          in: query
          description: |
            Encoded list of key value pairs for additional data.  Supported field types are:
            - label: string value
            - color: A hex color value (e.g. `#0a0a0a`)
            - select: an enumerate list of strings

            The fields are encoded using the following format:
            `<key1>~<value1>_<key2>~<value2>`

            Where:
            - `~`: key and value separator
            - `_`: key/value pair separator

            The following characters are treated as reserved, and if they appear within either
            the key or value they will be encoded using the value: `!<hex-code>`

            <table>
              <thead><td>Character</td><td>Encoded Value</td></thead>
              <tr><td>-</td><td>!2D</td></tr>
              <tr><td>.</td><td>!2E</td></tr>
              <tr><td>_</td><td>!5F</td></tr>
              <tr><td>~</td><td>!7E</td></tr>
            </table>

            The remainder special characters will be URL encoded.

            For example. If we have the following field structure:
            <table>
              <thead><td>Key</td><td>Value</td></thead>
              <tr><td>field-one</td><td>Has special chars: ".~_-"</td></tr>
              <tr><td>field_two</td><td>#ffffff</td></tr>
            </table>

            This would be encoded in the `additionalFields` query parameter as:
            `field!2Done~Has%20special%20chars%20%3A%20%22!2E!7E!5F!2D%22_field!5Ftwo~%23ffffff`
          schema:
            type: string
          examples:
            simple:
              value: key1~value1_key2~value2
              summary: Simple key value pairs with no encoding
            complex:
              value: "field!2Done~Has%20special%20chars%20%3A%20%22!2E!7E!5F!2D%22_field!5Ftwo~%23ffffff"
              summary: Complex key value pairs with URL encoding and embedded reserved character escapes
        - 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:
            gtin-list:
              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.

🚧
배너는 배너 X API 응답 기능 내에 있어야 합니다.

📘
이러한 사양은 변경될 수 있으며 통합자는 사양이 변경될 때마다 사전에 이를 통보받습니다.

사용자가 미리보기를 플랫폼에 로드하면 미리보기에 렌더링되는 정의된 매개 변수 세트로 GET 요청이 이루어집니다. 그런 다음 이는 플랫폼 내에서 아이프레임으로 표시됩니다.

요청은 아래 예시와 비슷하게 이루어집니다.

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

추가 필드

콘텐츠 표준은 키 쌍 값의 집합으로 additionalFields 를 지원합니다. 이는 미리보기용 쿼리 문자열에서 사용자 지정 방식으로 인코딩됩니다. 지원 필드 유형:

label: 문자열 값
color: 16진수 색상 값(예: #0a0a0a)
select: 문자열의 열거 목록

필드는 다음 형식으로 인코딩됩니다: <key1>~<value1>_<key2>~<value2>
위치:

~: 키와 값 구분 기호
_: 키/값 쌍 구분 기호

다음 문자는 예약된 것으로 처리되며 키 또는 값에 나타나는 경우 값을 사용하여 인코딩됩니다. !<hex-code>
문자

문자	인코딩된 값
-	!2D
.	!2E
_	!5F
~	!7E

나머지 특수 문자는 URL로 인코딩됩니다.

예를 들어 다음과 같은 필드 구조가 있는 경우

키	값
field-one	특수 문자 포함: ".~_-"
field_two	# ffffff

다음과 같이 additionalFields 쿼리 매개 변수에 인코딩됩니다: additionalFields=field!2Done~Has%20special%20chars%20%3A%20%22!2E!7E!5F!2D%22_field!5Ftwo~%23ffffff

배너 X 미리보기 통합

🚧
이것은 호스팅된 소매업체입니다

미리보기 사양을 통합하는 방법

🚧

📘

추가 필드

🚧이것은 호스팅된 소매업체입니다

미리보기 사양을 통합하는 방법

🚧

📘

추가 필드

🚧
이것은 호스팅된 소매업체입니다