> 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/fr/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).

# Outil de prévisualisation Banner X

Ce document décrit le processus permettant aux distributeurs d'intégrer un previewer de bannière X dans leur flux de travail. Cela permet un contrôle total sur le rendu de la prévisualisation, garantissant qu'il correspond à l'expérience du site web en direct.

{% hint style="info" %}
C'est une exigence d'intégration

Cette intégration du previewer garantit que votre Banner X Création est restituée correctement lors de la création et de la révision des campagnes, ce qui renforce la confiance des annonceurs et des distributeurs lors de la gestion des campagnes.
{% endhint %}

## Avantages d'un previewer

Un previewer offre plusieurs avantages :

* Les annonceurs peuvent prévisualiser l'apparence de leur bannière avant de lancer et de gérer leur campagne pour s'assurer qu'elle répond aux attentes et aux normes.
* Les distributeurs peuvent vérifier et approuver les bannières avant qu'elles ne soient mises en ligne sur leur site web, ce qui garantit la cohérence et le contrôle de la qualité.
* Toute modification apportée à votre site en direct (qui n'a pas d'impact sur les dimensions de la création) peut être effectuée sans dépendre de Epsilon Retail Media.

## Comment ça marche

Pour offrir aux annonceurs un aperçu en temps réel de la façon dont les bannières apparaîtront sur votre site, nous nous connectons directement à votre previewer hébergé. Cela garantit que les bannières s'affichent exactement comme elles le feraient sur votre site. Lorsque vous mettez à jour votre site, le previewer se met à jour automatiquement, éliminant ainsi toute dépendance à l'égard de Epsilon et maintenant le rendu des bannières parfaitement aligné avec vos dernières modifications.

## Intégration hébergée par le distributeur

Vous pouvez intégrer votre previewer de bannière dans notre plateforme en l'hébergeant sur votre site. Cela garantit que le previewer est intégré dans la fenêtre de la plateforme à l'aide d'une iframe.

* **Exigences d'hébergement** : Vous devez héberger le previewer sur une URL ou un lien que vous possédez et gérez. Cette approche offre une flexibilité totale pour le mettre à jour et le gérer au fur et à mesure que votre site et votre design évoluent, éliminant ainsi toute dépendance vis-à-vis de notre plateforme pour les modifications.
* **Recommandation d'hébergement** : Nous vous recommandons d'héberger le previewer sur une URL masquée, telle que retailer.com/banner-previewer. Cependant, vous avez la possibilité de choisir un emplacement approprié.
  * Cet emplacement peut être un emplacement hébergé externe qui ne se trouve pas sous votre domaine principal si nécessaire, comme un bucket de stockage accessible de l'extérieur ou une solution hébergée (qui reste sous votre maintenance).
* **Mises à jour du site en direct** : Vous pouvez mettre à jour la façon dont les images et le texte sont restitués sur votre site en direct. Toutes les modifications que vous apportez aux bannières sur le site en direct doivent automatiquement se refléter dans la plateforme via votre previewer externe.

<figure><img src="/files/Tgf4ax2rRHsXyvQwmpzn" alt="Screen Shot 2021-02-05 at 3.47.48 pm (1).png" width="100%"><figcaption><p>Image du previewer externe</p></figcaption></figure>

## Comment intégrer la spécification de prévisualisation

Pour afficher le contenu de notre plateforme sur votre previewer externe, hébergez un previewer de bannière isolé sur une page séparée que vous possédez et gérez. Nous suggérons d'utiliser une URL comme `https://www.<retailer.com>/banner-preview/bannerx`.

### OpenAPI spécification

Voici la OpenAPI spécification 3.0.3 pour implémenter la prévisualisation BannerX :

```
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" %}
Les bannières doivent rester dans les limites des capacités de la Banner X réponse d'API.
{% endhint %}

Lorsqu'un utilisateur charge le previewer dans la plateforme, une requête GET est effectuée avec un ensemble de paramètres définis qui sont restitués sur votre previewer. Cela est ensuite intégré dans une iframe au sein de la plateforme.

La requête ressemblera à l'exemple ci-dessous :

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

### Champs supplémentaires

Le standard de contenu prend en charge `additionalFields` sous forme d'ensemble de paires clé-valeur. Ceci est encodé d'une manière personnalisée dans la chaîne de requête pour le previewer. Les types de champs pris en charge sont :

* label\*\* : valeur chaîne de caractères
* **color** : Une valeur de couleur hexadécimale (ex. #0a0a0a)
* **select** : une liste énumérée de chaînes de caractères

Les champs sont encodés en utilisant le format suivant : `<key1>~<value1>_<key2>~<value2>` Où :

* `~`: séparateur de clé et de valeur
* `_`: séparateur de paire clé/valeur

### Caractères réservés

Les caractères suivants sont traités comme réservés, et s'ils apparaissent dans la clé ou la valeur, ils seront encodés en utilisant la valeur : `!<hex-code>`

| Caractère | Valeur encodée |
| --------- | -------------- |
| -         | !2D            |
| .         | !2E            |
| \_        | !5F            |
| \~        | !7E            |

Le reste des caractères spéciaux sera encodé en URL. Par exemple, si nous avons la structure de champ suivante :

| Clé        | Valeur                      |
| ---------- | --------------------------- |
| field-one  | Has special chars: ".\~\_-" |
| field\_two | # ffffff                    |

Ceci serait encodé dans le `additionalFields` paramètre de requête comme : `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/fr/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.