> 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/de/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).
# Banner X-Vorschau
Dieses Dokument beschreibt den Prozess für Händler zur Integration eines Banner-X-Vorschau-Tools in ihren Workflow. Dies ermöglicht die vollständige Kontrolle über das Rendering der Vorschau und stellt sicher, dass es mit dem Erlebnis auf der Live-Website übereinstimmt.
{% hint style="info" %}
Dies ist eine Integrationsanforderung
Diese Vorschau-Tool-Integration stellt sicher, dass Ihr Banner X Werbemittel bei der Erstellung und Überprüfung von Kampagnen korrekt gerendert wird. Das schafft Vertrauen sowohl bei Werbetreibenden als auch bei Händlern bei der Verwaltung von Kampagnen.
{% endhint %}
## Vorteile eines Vorschau-Tools
Ein Vorschau-Tool bietet mehrere Vorteile:
* Werbetreibende können das Erscheinungsbild ihres Banners vor dem Start und der Verwaltung ihrer Kampagne in der Vorschau anzeigen, um sicherzustellen, dass es den Erwartungen und Standards entspricht.
* Händler können Banner überprüfen und genehmigen, bevor sie live auf ihrer Website erscheinen, was Konsistenz und Qualitätskontrolle gewährleistet.
* Alle Änderungen an Ihrer Live-Website (die sich nicht auf die Abmessungen des Werbemittels auswirken) können ohne Abhängigkeit von vorgenommen werden Epsilon Retail Media.
## So funktioniert es
Um Werbetreibenden eine Echtzeit-Vorschau zu bieten, wie Banner auf Ihrer Website aussehen werden, verbinden wir uns direkt mit Ihrem gehosteten Vorschau-Tool. Dies stellt sicher, dass Banner genau so gerendert werden, wie sie auf Ihrer Website erscheinen würden. Wenn Sie Ihre Website aktualisieren, wird das Vorschau-Tool automatisch aktualisiert, wodurch die Abhängigkeit von aufgehoben wird Epsilon und das Banner-Rendering vollständig an Ihren neuesten Änderungen ausgerichtet bleibt.
## Händler-gehostete Integration
Sie können Ihr Banner-Vorschau-Tool in unsere Plattform integrieren, indem Sie es auf Ihrer Website hosten. Dies stellt sicher, dass das Vorschau-Tool über ein iframe in das Plattformfenster eingebettet ist.
* **Host-Anforderungen**: Sie müssen das Vorschau-Tool unter einer URL oder einem Link hosten, den Sie besitzen und verwalten. Dieser Ansatz bietet volle Flexibilität bei der Aktualisierung und Verwaltung im Zuge der Weiterentwicklung Ihrer Website und Ihres Designs, sodass keine Abhängigkeit von unserer Plattform für Änderungen besteht.
* **Hosting-Empfehlung**: Wir empfehlen, das Vorschau-Tool unter einer verborgenen URL zu hosten, wie z. B. retailer.com/banner-previewer. Sie können jedoch nach eigenem Ermessen einen geeigneten Ort wählen.
* Dieser Ort kann bei Bedarf ein extern gehosteter Ort sein, der sich nicht unter Ihrer Hauptdomain befindet, wie z. B. ein extern zugänglicher Storage Bucket oder eine gehostete Lösung (die weiterhin unter Ihrer Wartung steht).
* **Live-Website-Aktualisierungen**: Sie können aktualisieren, wie Bilder und Text auf Ihrer Live-Website gerendert werden. Alle Änderungen, die Sie an Bannern auf der Live-Website vornehmen, sollten sich automatisch über Ihr externes Vorschau-Tool in der Plattform widerspiegeln.
Bild des externen Vorschau-Tools
## So integrieren Sie die Vorschauspezifikation
Um Inhalte aus unserer Plattform auf Ihrem externen Vorschau-Tool anzuzeigen, hosten Sie ein isoliertes Banner-Vorschau-Tool auf einer separaten Seite, die Sie besitzen und verwalten. Wir empfehlen die Verwendung einer URL wie `https://www./banner-preview/bannerx`.
### OpenAPI Spezifikation
Nachfolgend finden Sie die OpenAPI 3.0.3-Spezifikation für die Implementierung der BannerX-Vorschau:
```
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" %}
Banner müssen im Rahmen der Möglichkeiten der Banner X API-Antwort bleiben.
{% endhint %}
Wenn ein Benutzer die Vorschau in der Plattform lädt, wird eine GET-Anforderung mit einem Satz definierter Parameter gestellt, die in Ihrer Vorschau gerendert werden. Diese wird dann innerhalb der Plattform als iframe eingebunden.
Die Anforderung sieht ähnlich aus wie im folgenden Beispiel:
```
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
```
### Zusätzliche Felder
Der Inhaltsstandard unterstützt `additionalFields` als ein Satz von Schlüssel-Wert-Paaren. Dies wird in der Abfragezeichenfolge für die Vorschau auf benutzerdefinierte Weise codiert. Unterstützte Feldtypen sind:
* label\*\*: Zeichenfolgenwert
* **color**: Ein Hex-Farbwert (z. B. #0a0a0a)
* **select**: eine aufgezählte Liste von Zeichenfolgen
Die Felder werden im folgenden Format codiert: `~_~` Wobei:
* `~`: Schlüssel- und Wert-Trennzeichen
* `_`: Schlüssel/Wert-Paar-Trennzeichen
### Reservierte Zeichen
Die folgenden Zeichen werden als reserviert behandelt, und wenn sie entweder im Schlüssel oder im Wert vorkommen, werden sie mit dem Wert codiert: `!`
| Zeichen | Codierter Wert |
| ------- | -------------- |
| - | !2D |
| . | !2E |
| \_ | !5F |
| \~ | !7E |
Die übrigen Sonderzeichen werden URL-codiert. Wenn wir beispielsweise die folgende Feldstruktur haben:
| Schlüssel | Wert |
| ---------- | ------------------------------- |
| field-one | Enthält Sonderzeichen: ".\~\_-" |
| field\_two | # ffffff |
Dies würde in dem `additionalFields` Abfrageparameter codiert werden als: `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/de/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.