> 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/sv/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md).
# Förhandsgranskare för Banner X
Detta dokument beskriver processen för återförsäljare att integrera en Banner X-previewer i sitt arbetsflöde. Detta möjliggör fullständig kontroll över förhandsgranskningen, vilket säkerställer att den matchar upplevelsen på den levande webbplatsen.
{% hint style="info" %}
Detta är ett integrationskrav
Denna previewer-integration säkerställer att din Banner X annonskreativ återges korrekt när du skapar och granskar kampanjer, vilket skapar förtroende hos både annonsörer och återförsäljare vid hantering av kampanjer.
{% endhint %}
## Fördelar med en previewer
En previewer erbjuder flera fördelar:
* Annonsörer kan förhandsgranska sin banners utseende innan de startar och hanterar sin kampanj för att säkerställa att den uppfyller förväntningar och standarder.
* Återförsäljare kan granska och godkänna banners innan de visas live på deras webbplats, vilket säkerställer konsekvens och kvalitetskontroll.
* Eventuella ändringar på din live-webbplats (som inte påverkar storleken på ditt annonskreativ) kan göras utan beroende av Epsilon Retail Media.
## Hur det fungerar
För att ge annonsörer en förhandsgranskning i realtid av hur banners kommer att se ut på din webbplats, ansluter vi direkt till din hostade previewer. Detta säkerställer att banners återges exakt som de skulle göra på din webbplats. När du uppdaterar din webbplats uppdateras previewern automatiskt, vilket eliminerar beroendet av Epsilon och håller banneråtergivningen helt anpassad till dina senaste ändringar.
## Integration hostad av återförsäljaren
Du kan integrera din banner-previewer i vår plattform genom att hosta den på din webbplats. Detta säkerställer att previewern bäddas in i plattformsfönstret med hjälp av en iframe.
* **Värdkrav**: Du måste hosta previewern på en URL eller länk som du äger och hanterar. Detta tillvägagångssätt ger full flexibilitet att uppdatera och hantera den när din webbplats och design utvecklas, vilket eliminerar allt beroende av vår plattform för ändringar.
* **Hostingrekommendation**: Vi rekommenderar att du hostar previewern på en dold URL, som retailer.com/banner-previewer. Du har dock frihet att välja en lämplig plats.
* Denna plats kan vid behov vara en extern hostad plats som inte ligger under din huvuddomän, till exempel en externt tillgänglig lagringsbucket eller hostad lösning (som fortfarande underhålls av dig).
* **Uppdateringar på live-webbplatsen**: Du kan uppdatera hur bilder och text återges på din live-webbplats. Alla ändringar du gör på banners på live-webbplatsen bör automatiskt återspeglas i plattformen via din externa previewer.
Bild för extern previewer
## Hur man integrerar preview-specifikationen
För att visa innehåll från vår plattform på din externa previewer, hosta en isolerad banner-previewer på en separat sida som du äger och hanterar. Vi föreslår att du använder en URL som `https://www./banner-preview/bannerx`.
### OpenAPI specifikation
Nedan är OpenAPI 3.0.3-specifikationen för att implementera BannerX-preview:
```
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" %}
Banners måste hålla sig inom funktionerna för Banner X API-svar.
{% endhint %}
När en användare läser in previewern i plattformen görs en GET-begäran med en uppsättning definierade parametrar som återges på din previewer. Detta läggs sedan i en iframe inom plattformen.
Begäran kommer att se ut ungefär som exemplet nedan:
```
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
```
### Ytterligare fält
Innehållsstandarden stöder `additionalFields` som en uppsättning nyckel/värde-par. Detta kodas på ett anpassat sätt i frågesträngen för previewern. Fälttyper som stöds är:
* label\*\*: strängvärde
* **color**: Ett hex-färgvärde (t.ex. #0a0a0a)
* **select**: en numrerad lista med strängar
Fälten kodas med följande format: `~_~` Där:
* `~`: separator för nyckel och värde
* `_`: separator för nyckel/värde-par
### Reserverade tecken
Följande tecken behandlas som reserverade, och om de visas i antingen nyckeln eller värdet kommer de att kodas med värdet: `!`
| Tecken | Kodat värde |
| ------ | ----------- |
| - | !2D |
| . | !2E |
| \_ | !5F |
| \~ | !7E |
Återstående specialtecken kommer att URL-kodas. Om vi till exempel har följande fältstruktur:
| Nyckel | Värde |
| ---------- | --------------------------- |
| field-one | Har specialtecken: ".\~\_-" |
| field\_two | # ffffff |
Detta skulle kodas i `additionalFields` frågeparameter som: `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/sv/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.