この文書は、小売業者がバナーXプレビューアをワークフローに統合するプロセスを説明しています。これにより、プレビューのレンダリングを完全に制御し、ライブウェブサイトのエクスペリエンスと一致させることができます。

📘
これは統合要件です
このプレビューアーの統合により、キャンペーンを作成・確認する際にバナーXのクリエイティブが正しく表示されるため、広告主だけでなく小売業者も安心してキャンペーンを管理することができます。

プレビューアーの利点

プレビューアーには、いくつかの利点があります。

広告主は、キャンペーンを開始および管理する前に、バナーの外観をプレビューし、期待と基準を満たしていることを確認できます。
小売業者は、バナーがウェブサイトに表示される前に確認して承認することで、一貫性と品質管理を確保できます。
ライブサイトへの変更（クリエイティブサイズに影響しないもの）は、Epsilon Retail Mediaに依存せずに行うことができます。

小売業者がホストする統合

自社サイトでバナープレビューアーをホストすることで、当社のプラットフォームに統合することができます。これにより、プレビューアーがiframeを使用してプラットフォームウィンドウに確実に埋め込まれるようになります。

ホスト要件：プレビューアーは、自社が所有・管理しているURLまたはリンクでホストする必要があります。このアプローチにより、サイトやデザインの進化に合わせて更新および管理する柔軟性が完全に確保され、変更の際に当社のプラットフォームに依存する必要がなくなります。
ホスティングの推奨：プレビューアーは、retailer.com/banner-previewerなどの隠しURLでホスティングすることをお勧めします。ただし、適切な場所の選択はお客様の裁量に委ねられます。
- この場所は、必要に応じて、外部からアクセス可能なストレージバケットやホストソリューション（まだメンテナンス中）など、メインドメインにない外部にホストされている場所でもかまいません。
ライブサイトの更新：ライブサイトでの画像やテキストのレンダリング方法を更新することができます。本番サイトのバナーに加えた変更は、外部プレビューアーを通じてプラットフォームに自動的に反映されます。

プレビューの仕様を組み込むには

外部プレビューアーに当社プラットフォームのコンテンツを表示するには、所有および管理する別のページで独立したバナープレビューアーをホストします。次のようなURLを使用することをお勧めします。 https://www.<retailer.com>/banner-preview/bannerx.

OpenAPIの仕様

以下は、バナーX プレビューを実装するための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.

🚧
バナーは、Banner X APIのレスポンスの機能内に収まっている必要があります。

ユーザーがプラットフォームでプレビューアを読み込むと、定義されたパラメータのセットで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: 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プレビューアー

📘
これは統合要件です

プレビューアーの利点

小売業者がホストする統合

プレビューの仕様を組み込むには

OpenAPIの仕様

🚧

追加フィールド

予約済み文字

📘これは統合要件です

プレビューアーの利点

小売業者がホストする統合

プレビューの仕様を組み込むには

OpenAPIの仕様

🚧

追加フィールド

予約済み文字

📘
これは統合要件です