> 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/it/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).
# Visualizzatore di anteprima Banner X
Questo documento illustra il processo con cui i retailer possono integrare un'anteprima di banner X nel proprio flusso di lavoro. Ciò consente un controllo completo sul rendering dell'anteprima, garantendo che corrisponda all'esperienza del sito web live.
{% hint style="info" %}
Questo è un requisito di integrazione
Questa integrazione dell'anteprima garantisce che il tuo Banner X materiale creativo venga renderizzato correttamente durante la creazione e la revisione delle campagne, infondendo fiducia sia negli inserzionisti che nei retailer durante la gestione delle campagne.
{% endhint %}
## Vantaggi di un'anteprima
Un'anteprima offre diversi vantaggi:
* Gli inserzionisti possono visualizzare l'aspetto del proprio banner prima di lanciare e gestire la campagna, per assicurarsi che soddisfi le aspettative e gli standard.
* I retailer possono visualizzare e approvare i banner prima che appaiano live sul loro sito web, garantendo coerenza e controllo della qualità.
* Qualsiasi modifica al tuo sito live (che non influisca sulle dimensioni del materiale creativo) può essere apportata senza alcuna dipendenza da Epsilon Retail Media.
## Come funziona
Per offrire agli inserzionisti un'anteprima in tempo reale di come appariranno i banner sul tuo sito, ci colleghiamo direttamente al tuo strumento di anteprima ospitato. Ciò garantisce che i banner vengano renderizzati esattamente come farebbero sul tuo sito. Man mano che aggiorni il tuo sito, l'anteprima si aggiorna automaticamente, eliminando la dipendenza da Epsilon e mantenendo il rendering dei banner completamente allineato con le tue ultime modifiche.
## Integrazione ospitata dal retailer
Puoi integrare la tua anteprima di banner nella nostra piattaforma ospitandola sul tuo sito. Ciò garantisce che l'anteprima sia incorporata nella finestra della piattaforma tramite un iframe.
* **Requisiti di hosting**: Devi ospitare l'anteprima su un URL o link di tua proprietà e gestito da te. Questo approccio offre la massima flessibilità per aggiornarla e gestirla man mano che il tuo sito e il tuo design si evolvono, eliminando qualsiasi dipendenza dalla nostra piattaforma per le modifiche.
* **Raccomandazione per l'hosting**: Consigliamo di ospitare l'anteprima su un URL nascosto, come retailer.com/banner-previewer. Tuttavia, hai la discrezione di scegliere una posizione appropriata.
* Questa posizione può essere una posizione ospitata esterna che non si trova sotto il tuo dominio principale, se necessario, come un bucket di archiviazione accessibile dall'esterno o una soluzione ospitata (che sia comunque sotto la tua manutenzione).
* **Aggiornamenti del sito live**: Puoi aggiornare il modo in cui le immagini e il testo vengono renderizzati sul tuo sito live. Qualsiasi modifica apportata ai banner sul sito live dovrebbe riflettersi automaticamente nella piattaforma tramite la tua anteprima esterna.
Immagine dell'anteprima esterna
## Come integrare le specifiche dell'anteprima
Per visualizzare i contenuti della nostra piattaforma sulla tua anteprima esterna, ospita un'anteprima di banner isolata su una pagina separata di tua proprietà e gestita da te. Suggeriamo di utilizzare un URL come `https://www./banner-preview/bannerx`.
### OpenAPI specifica
Di seguito sono riportate le OpenAPI specifiche 3.0.3 per l'implementazione dell'anteprima 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. ``, `` and `` 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:
`~_~`
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: `!`
Character
Encoded Value
-
!2D
.
!2E
_
!5F
~
!7E
The remainder special characters will be URL encoded.
For example. If we have the following field structure:
Key
Value
field-one
Has special chars: ".~_-"
field_two
#ffffff
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" %}
I banner devono rimanere entro le funzionalità della Banner X risposta API.
{% endhint %}
Quando un utente carica l'anteprima nella piattaforma, viene effettuata una richiesta GET con un set di parametri definiti che vengono renderizzati sulla tua anteprima. Questa viene quindi inserita in un iframe all'interno della piattaforma.
La richiesta sarà simile all'esempio seguente:
```
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>ins=7459770>ins=59398>ins=7895365
```
### Campi aggiuntivi
Lo standard di contenuto supporta `additionalFields` come insieme di coppie chiave-valore. Questo viene codificato in modo personalizzato nella stringa di query per l'anteprima. I tipi di campi supportati sono:
* label\*\*: valore stringa
* **color**: un valore cromatico esadecimale (ad es. #0a0a0a)
* **select**: un elenco enumerato di stringhe
I campi sono codificati utilizzando il seguente formato: `~_~` Dove:
* `~`: separatore di chiave e valore
* `_`: separatore di coppie chiave/valore
### Caratteri riservati
I seguenti caratteri sono trattati come riservati e, se compaiono all'interno della chiave o del valore, verranno codificati utilizzando il valore: `!`
| Carattere | Valore codificato |
| --------- | ----------------- |
| - | !2D |
| . | !2E |
| \_ | !5F |
| \~ | !7E |
I restanti caratteri speciali saranno codificati per URL. Ad esempio, se abbiamo la seguente struttura di campo:
| Chiave | Valore |
| ---------- | ------------------------------- |
| field-one | Ha caratteri speciali: ".\~\_-" |
| field\_two | # ffffff |
Questo verrebbe codificato nel `additionalFields` parametro di query come: `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/it/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md?ask=&goal=
```
`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.