> 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/sk/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).
# Nástroj na náhľad Banner X
Tento dokument popisuje proces pre predajcov, ako integrovať náhľadový nástroj bannerov X do ich pracovného postupu. To umožňuje úplnú kontrolu nad vykresľovaním náhľadu a zabezpečuje, že zodpovedá zážitku zo živých webových stránok.
{% hint style="info" %}
Toto je požiadavka na integráciu
Táto integrácia náhľadového nástroja zabezpečuje, že váš Banner X reklamný materiál sa pri vytváraní a kontrole kampaní zobrazuje správne, čo vytvára dôveru u inzerentov aj predajcov pri spravovaní kampaní.
{% endhint %}
## Výhody náhľadového nástroja
Náhľadový nástroj ponúka niekoľko výhod:
* Inzerenti si môžu pred spustením a spravovaním svojej kampane pozrieť náhľad vzhľadu svojho bannera, aby sa uistili, že spĺňa očakávania a štandardy..
* Predajcovia môžu skontrolovať a schváliť bannery pred ich zverejnením na svojej webovej stránke, čím sa zabezpečí konzistentnosť a kontrola kvality.
* Akékoľvek zmeny na vašej živej stránke (ktoré nemajú vplyv na rozmery reklamného materiálu) je možné vykonať bez závislosti od Epsilon Retail Media.
## Ako to funguje
Aby sme inzerentom poskytli náhľad v reálnom čase, ako sa bannery zobrazia na vašej stránke, pripájame sa priamo k vášmu hostovanému náhľadovému nástroju. Tým sa zabezpečí, že bannery sa vykreslia presne tak, ako by sa zobrazili na vašej stránke. Keď aktualizujete svoju stránku, náhľadový nástroj sa automaticky aktualizuje, čím sa eliminuje závislosť od Epsilon a vykresľovanie bannerov zostáva plne v súlade s vašimi najnovšími zmenami.
## Integrácia hostovaná predajcom
Náhľadový nástroj bannerov môžete integrovať do našej platformy tak, že ho budete hostovať na svojej stránke. Tým sa zabezpečí, že náhľadový nástroj bude vložený do okna platformy pomocou iframe.
* **Požiadavky na hosting**: Náhľadový nástroj musíte hostovať na URL alebo odkaze, ktorý vlastníte a spravujete. Tento prístup poskytuje plnú flexibilitu pri jeho aktualizácii a správe podľa toho, ako sa vyvíja vaša stránka a dizajn, čím sa eliminuje akákoľvek závislosť od našej platformy pri zmenách.
* **Odporúčanie pre hosting**: Odporúčame hostovať náhľadový nástroj na skrytej URL, ako je retailer.com/banner-previewer. Máte však právo zvoliť si vhodné umiestnenie.
* Toto umiestnenie môže byť v prípade potreby externé hostované umiestnenie, ktoré nespadá pod vašu hlavnú doménu, ako je externejšie prístupné úložisko (storage bucket) alebo hostované riešenie (ktoré je stále pod vašou údržbou).
* **Aktualizácie živej stránky**: Môžete aktualizovať spôsob vykresľovania obrázkov a textu na vašej živej stránke. Všetky zmeny, ktoré vykonáte na banneroch na živej stránke, by sa mali automaticky prejaviť v platforme prostredníctvom vášho externého náhľadového nástroja.
Obrázok externého náhľadového nástroja
## Ako integrovať špecifikáciu náhľadu
Ak chcete zobraziť obsah z našej platformy na vašom externom náhľadovom nástroji, hostujte izolovaný náhľadový nástroj bannerov na samostatnej stránke, ktorú vlastníte a spravujete. Odporúčame použiť URL ako `https://www./banner-preview/bannerx`.
### OpenAPI špecifikácia
Nižšie je OpenAPI špecifikácia 3.0.3 pre implementáciu náhľadu 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" %}
Bannery musia zostávať v rámci možností Banner X API odpovede.
{% endhint %}
Keď používateľ načíta náhľadový nástroj v platforme, vygeneruje sa požiadavka GET s množstvom definovaných parametrov, ktoré sa vykreslia vo vašom náhľadovom nástroji. Ten je potom vložený cez iframe v rámci platformy.
Požiadavka bude vyzerať podobne ako v príklade nižšie:
```
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
```
### Dodatočné polia
Štandard obsahu podporuje `additionalFields` ako množinu párov kľúč-hodnota. Toto je kódované vlastným spôsobom v dopytovom reťazci (query string) pre náhľadový nástroj. Podporované typy polí sú:
* label\*\*: reťazcová hodnota (string)
* **color**: hexadecimálna hodnota farby (napr. #0a0a0a)
* **select**: vymenovaný zoznam reťazcov (enumerate list of strings)
Polia sú kódované pomocou nasledujúceho formátu: `~_~` Kde:
* `~`: oddeľovač kľúča a hodnoty
* `_`: oddeľovač párov kľúč/hodnota
### Vyhradené znaky
Nasledujúce znaky sa považujú za vyhradené a ak sa objavia v kľúči alebo hodnote, budú zakódované pomocou hodnoty: `!`
| Znak | Zakódovaná hodnota |
| ---- | ------------------ |
| - | !2D |
| . | !2E |
| \_ | !5F |
| \~ | !7E |
Pobočné špeciálne znaky budú zakódované pomocou URL encodingu. Napríklad, ak máme nasledujúcu štruktúru poľa:
| Kľúč | Hodnota |
| ---------- | ---------------------------------- |
| field-one | Obsahuje špeciálne znaky: ".\~\_-" |
| field\_two | # ffffff |
Toto by bolo zakódované v `additionalFields` query parametri ako: `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/sk/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.