> 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/pt-br/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).
# Visualizador do Banner X
Este documento descreve o processo para que os varejistas integrem um visualizador de banner X em seu fluxo de trabalho. Isso permite o controle total sobre a renderização da visualização, garantindo que ela corresponda à experiência do site ao vivo.
{% hint style="info" %}
Este é um requisito de integração
Esta integração do visualizador garante que seu Banner X criativo seja renderizado corretamente ao criar e revisar campanhas, gerando confiança tanto para anunciantes quanto para varejistas ao gerenciar campanhas.
{% endhint %}
## Benefícios de um visualizador
Um visualizador oferece várias vantagens:
* Os anunciantes podem visualizar a aparência de seu banner antes de lançar e gerenciar sua campanha para garantir que ela atenda às expectativas e padrões.
* Os varejistas podem revisar e aprovar banners antes que eles entrem no ar em seu site, garantindo consistência e controle de qualidade.
* Quaisquer alterações em seu site ao vivo (que não impactem as dimensões do criativo) podem ser feitas sem dependência de Epsilon Retail Media.
## Como funciona
Para dar aos anunciantes uma visualização em tempo real de como os banners aparecerão em seu site, nós nos conectamos diretamente ao seu visualizador hospedado. Isso garante que os banners sejam renderizados exatamente como seriam em seu site. Conforme você atualiza seu site, o visualizador é atualizado automaticamente, eliminando a dependência de Epsilon e mantendo a renderização do banner totalmente alinhada com suas alterações mais recentes.
## Integração hospedada pelo varejista
Você pode integrar seu visualizador de banner à nossa plataforma hospedando-o em seu site. Isso garante que o visualizador seja incorporado na janela da plataforma usando um iframe.
* **Requisitos de hospedagem**: Você deve hospedar o visualizador em um URL ou link que possui e gerencia. Essa abordagem oferece flexibilidade total para atualizá-lo e gerenciá-lo à medida que seu site e design evoluem, eliminando qualquer dependência da nossa plataforma para alterações.
* **Recomendação de hospedagem**: Recomendamos hospedar o visualizador em um URL oculto, como varejista.com/banner-previewer. No entanto, você tem a discrição de escolher um local apropriado.
* Este local pode ser um local hospedado externalizado que não esteja sob seu domínio principal, se necessário, como um bucket de armazenamento acessível externamente ou uma solução hospedada (que ainda esteja sob sua manutenção).
* **Atualizações do site ao vivo**: Você pode atualizar como imagens e textos são renderizados em seu site ao vivo. Quaisquer alterações feitas nos banners no site ao vivo devem ser refletidas automaticamente na plataforma por meio do seu visualizador externo.
Imagem do visualizador externo
## Como integrar a especificação de visualização
Para exibir conteúdo de nossa plataforma em seu visualizador externo, hospede um visualizador de banner isolado em uma página separada que você possui e gerencia. Sugerimos usar um URL como `https://www./banner-preview/bannerx`.
### OpenAPI especificação
Abaixo está a OpenAPI especificação 3.0.3 para implementar a visualização do 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" %}
Os banners devem permanecer dentro das capacidades da Banner X resposta da API.
{% endhint %}
Quando um usuário carrega o visualizador na plataforma, uma requisição GET é feita com um conjunto de parâmetros definidos que são renderizados em seu visualizador. Isso é então exibido em um iframe dentro da plataforma.
A requisição será semelhante ao exemplo abaixo:
```
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 adicionais
O padrão de conteúdo suporta `additionalFields` como um conjunto de pares de chave e valor. Isso é codificado de maneira personalizada na string de consulta para o visualizador. Os tipos de campo suportados são:
* label\*\*: valor string
* **color**: Um valor de cor hex (ex.: #0a0a0a)
* **select**: uma lista enumerada de strings
Os campos são codificados usando o seguinte formato: `~_~` Onde:
* `~`: separador de chave e valor
* `_`: separador de par chave/valor
### Caracteres reservados
Os seguintes caracteres são tratados como reservados e, se aparecerem na chave ou no valor, serão codificados usando o valor: `!`
| Caractere | Valor codificado |
| --------- | ---------------- |
| - | !2D |
| . | !2E |
| \_ | !5F |
| \~ | !7E |
Os demais caracteres especiais serão codificados por URL. Por exemplo, se tivermos a seguinte estrutura de campo:
| Chave | Valor |
| ---------- | ------------------------------------- |
| field-one | Possui caracteres especiais: ".\~\_-" |
| field\_two | # ffffff |
Isso seria codificado no `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/pt-br/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.