> 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/ja/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/HR0p1uQEg1ZFFDiEaQUt" 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 仕様

以下は BannerX プレビューを実装するための OpenAPI 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/ja/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.