> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/ko/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).

# Banner X 미리보기

이 문서는 리테일러가 배너 X 미리보기를 워크플로에 통합하는 프로세스를 설명합니다. 이를 통해 미리보기 렌더링을 완벽하게 제어하여 실제 웹사이트 환경과 일치하도록 할 수 있습니다.

{% hint style="info" %}
이것은 통합 요구 사항입니다

이 미리보기 통합은 귀하의 Banner X 크리에이티브가 캠페인을 생성하고 검토할 때 올바르게 렌더링되도록 하여, 캠페인을 관리할 때 광고주와 리테일러 모두에게 신뢰를 형성합니다.
{% endhint %}

## 미리보기의 장점

미리보기는 다음과 같은 몇 가지 장점을 제공합니다.

* 광고주는 캠페인을 실행하고 관리하기 전에 배너가 어떻게 보이는지 미리 보고 기대치와 표준을 충족하는지 확인할 수 있습니다.
* 리테일러는 배너가 웹사이트에 라이브로 게시되기 전에 이를 검토하고 승인하여 일관성과 품질 관리를 보장할 수 있습니다.
* 실제 사이트의 모든 변경 사항(크리에이티브 크기에 영향을 주지 않는)은 다음에 의존하지 않고 수행할 수 있습니다. Epsilon Retail Media.

## 작동 방식

배너가 사이트에 어떻게 표시될지 광고주에게 실시간 미리보기를 제공하기 위해, 당사는 귀하가 호스팅하는 미리보기에 직접 연결합니다. 이를 통해 배너가 귀하의 사이트에서와 똑같이 렌더링됩니다. 사이트를 업데이트하면 미리보기가 자동으로 업데이트되므로 다음에 대한 의존성이 제거됩니다. Epsilon 그리고 배너 렌더링을 최신 변경 사항과 완전히 일치하게 유지합니다.

## 리테일러 호스팅 통합

배너 미리보기를 사이트에 호스팅하여 플랫폼에 통합할 수 있습니다. 이를 통해 미리보기가 iframe을 사용하여 플랫폼 창에 임베드됩니다.

* **호스트 요구 사항**: 귀하가 소유하고 관리하는 URL 또는 링크에 미리보기를 호스팅해야 합니다. 이 방식을 사용하면 사이트와 디자인이 발전함에 따라 이를 업데이트하고 관리할 수 있는 완전한 유연성이 제공되므로 변경 사항에 대해 당사 플랫폼에 의존할 필요가 없어집니다.
* **호스팅 권장 사항**: retailer.com/banner-previewer와 같은 숨겨진 URL에 미리보기를 호스팅하는 것을 권장합니다. 그러나 적절한 위치를 선택할 수 있는 재량권은 귀하에게 있습니다.
  * 이 위치는 필요한 경우 외부에서 접근 가능한 스토리지 버킷이나 호스팅된 솔루션(여전히 귀하가 유지 관리하는)과 같이 기본 도메인 아래에 있지 않은 외부 호스팅 위치일 수 있습니다.
* **실제 사이트 업데이트**: 실제 사이트에서 이미지와 텍스트가 렌더링되는 방식을 업데이트할 수 있습니다. 실제 사이트의 배너에 적용한 모든 변경 사항은 외부 미리보기를 통해 플랫폼에 자동으로 반영되어야 합니다.

<figure><img src="/files/3t1FdEZYcWAeWHSFqGLz" alt="Screen Shot 2021-02-05 at 3.47.48 pm (1).png" width="100%"><figcaption><p>외부 미리보기 이미지</p></figcaption></figure>

## 미리보기 사양 통합 방법

외부 미리보기에 당사 플랫폼의 콘텐츠를 표시하려면 소유하고 관리하는 별도의 페이지에 격리된 배너 미리보기를 호스팅하세요. 다음과 같은 URL을 사용하는 것이 좋습니다. `https://www.<retailer.com>/banner-preview/bannerx`.

### OpenAPI 사양

아래는 OpenAPI BannerX 미리보기를 구현하기 위한 3.0.3 사양입니다.

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

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.
```

{% hint style="warning" %}
배너는 다음의 기능 범주 내에 남아 있어야 합니다. Banner X API 응답.
{% endhint %}

사용자가 플랫폼에서 미리보기 도구를 로드하면 미리보기 도구에 렌더링되는 정의된 매개변수 세트와 함께 GET 요청이 이루어집니다. 그런 다음 이는 플랫폼 내에서 iframe으로 처리됩니다.

요청은 아래 예시와 유사합니다.

```
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**: Hex 색상 값 (예: #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`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/integration/ko/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.