> 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/es/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).
# Vista previa de Banner X
Este documento describe el proceso para que los minoristas integren un previsualizador de X de banner en su flujo de trabajo. Esto permite un control total sobre la representación de la vista previa, garantizando que coincida con la experiencia del sitio web en vivo.
{% hint style="info" %}
Este es un requisito de integración
Esta integración del visor de vista previa garantiza que su Banner X creatividad se represente correctamente al crear y revisar campañas, lo que genera confianza tanto en los anunciantes como en los minoristas al gestionar las campañas.
{% endhint %}
## Beneficios de un visor de vista previa
Un visor de vista previa ofrece varias ventajas:
* Los anunciantes pueden previsualizar la apariencia de su banner antes de lanzar y gestionar su campaña para asegurarse de que cumple con las expectativas y los estándares.
* Los minoristas pueden revisar y aprobar los banners antes de que aparezcan en vivo en su sitio web, garantizando la coherencia y el control de calidad.
* Cualquier cambio en su sitio en vivo (que no afecte a las dimensiones de la creatividad) se puede realizar sin depender de Epsilon Retail Media.
## Cómo funciona
Para ofrecer a los anunciantes una vista previa en tiempo real de cómo aparecerán los banners en su sitio, nos conectamos directamente a su visor de vista previa alojado. Esto garantiza que los banners se representen exactamente como lo harían en su sitio. A medida que actualiza su sitio, el visor de vista previa se actualiza automáticamente, eliminando la dependencia de Epsilon y manteniendo la representación del banner totalmente alineada con sus últimos cambios.
## Integración alojada por el minorista
Puede integrar su visor de vista previa de banners en nuestra plataforma alojándolo en su sitio. Esto garantiza que el visor de vista previa quede incrustado en la ventana de la plataforma mediante un iframe.
* **Requisitos de alojamiento**: Debe alojar el visor de vista previa en una URL o enlace que sea de su propiedad y que usted gestione. Este enfoque proporciona total flexibilidad para actualizarlo y gestionarlo a medida que evolucionan su sitio y su diseño, eliminando cualquier dependencia de nuestra plataforma para realizar cambios.
* **Recomendación de alojamiento**: Recomendamos alojar el visor de vista previa en una URL oculta, como retailer.com/banner-previewer. Sin embargo, tiene la discreción de elegir una ubicación adecuada.
* Esta ubicación puede ser una ubicación alojada externalizada que no esté bajo su dominio principal si es necesario, como un contenedor de almacenamiento accesible externamente o una solución alojada (que siga estando bajo su mantenimiento).
* **Actualizaciones del sitio en vivo**: Puede actualizar cómo se representan las imágenes y el texto en su sitio en vivo. Cualquier cambio que realice en los banners del sitio en vivo debería reflejarse automáticamente en la plataforma a través de su visor de vista previa externo.
Imagen del visor de vista previa externo
## Cómo integrar la especificación de vista previa
Para mostrar contenido de nuestra plataforma en su visor de vista previa externo, aloje un visor de vista previa de banners aislado en una página independiente que sea de su propiedad y que usted gestione. Sugerimos utilizar una URL como `https://www./banner-preview/bannerx`.
### OpenAPI especificación
A continuación se muestra la OpenAPI especificación 3.0.3 para implementar la vista previa de 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" %}
Los banners deben permanecer dentro de las capacidades de la Banner X respuesta de la API.
{% endhint %}
Cuando un usuario carga el visor de vista previa en la plataforma, se realiza una solicitud GET con un conjunto de parámetros definidos que se representan en su visor de vista previa. Esto se incrusta mediante un iframe dentro de la plataforma.
La solicitud será similar al siguiente ejemplo:
```
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
```
### Campos adicionales
El estándar de contenido admite `additionalFields` como un conjunto de pares clave-valor. Esto se codifica de una manera personalizada en la cadena de consulta para el visor de vista previa. Los tipos de campos admitidos son:
* label\*\*: valor de cadena de texto
* **color**: Un valor de color hexadecimal (por ejemplo, #0a0a0a)
* **select**: una lista enumerada de cadenas de texto
Los campos se codifican utilizando el siguiente formato: `~_~` Donde:
* `~`: separador de clave y valor
* `_`: separador de par clave/valor
### Caracteres reservados
Los siguientes caracteres se tratan como reservados y, si aparecen dentro de la clave o del valor, se codificarán utilizando el valor: `!`
| Carácter | Valor codificado |
| -------- | ---------------- |
| - | !2D |
| . | !2E |
| \_ | !5F |
| \~ | !7E |
El resto de caracteres especiales se codificarán en la URL. Por ejemplo, si tenemos la siguiente estructura de campo:
| Clave | Valor |
| ---------- | ------------------------------------- |
| field-one | Tiene caracteres especiales: ".\~\_-" |
| field\_two | # ffffff |
Esto se codificaría en el `additionalFields` parámetro de consulta como: `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/es/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.