Trong trình tạo Biểu ngữ X, chúng tôi cung cấp trình xem trước cho nhà bán lẻ và nhà quảng cáo, cho phép:
- Nhà quảng cáo xem trước giao diện biểu ngữ trước khi khởi chạy chiến dịch
- Nhà quảng cáo xem biểu ngữ trong trình quản lý chiến dịch
- Nhà bán lẻ xem lại biểu ngữ trước khi chấp thuận cho biểu ngữ xuất hiện trên trang web.
Với các nhà bán lẻ nào muốn tùy chỉnh hiển thị biểu ngữ x, bạn có thể tích hợp trình xem trước biểu ngữ vào nền tảng của chúng tôi thông qua trình xem trước được lưu trữ trên trang web của bạn và sử dụng iframe trong cửa sổ nền tảng.
Đây là nhà bán lẻ được lưu trữ
Là nhà bán lẻ, bạn sẽ cần lưu trữ nội dung này trên url hoặc liên kết bạn sở hữu và quản lý.
Việc này giúp bạn hoàn toàn chủ động trong việc quản lý và cập nhật trang này khi trang web hay thiết kế trang web thay đổi - tức là bạn sẽ không phải phụ thuộc vào nền tảng của chúng tôi khi muốn thay đổi gì đó.
Nói chung, chúng tôi khuyên bạn nên lưu trữ nội dung này trên trang web của mình tại một URL ẩn, ví dụ như store.com/banner-previewer, nhưng bạn có quyền quyết định nơi nội dung được lưu trữ.
Bạn cũng có thể tùy ý cập nhật cách hiển thị hình ảnh và văn bản được cấp phát trên trang web đang hoạt động của bạn. Mọi thay đổi đối với biểu ngữ trên trang web đang hoạt động sẽ được phản ánh ngay tức thì trên nền tảng thông qua trình xem trước bên ngoài của bạn.
Hình ảnh trình xem trước bên ngoài
Cách tích hợp quy cách xem trước
Để hiển thị nội dung được nền tảng của chúng tôi chuyển đến trình xem trước bên ngoài của bạn, bạn sẽ cần lưu trữ trình xem trước biểu ngữ tách riêng của mình trên một trang riêng biệt do nhà bán lẻ sở hữu và quản lý. Chúng tôi đề nghị https://www.<retailer.com>/banner-preview/bannerx.
Bên dưới là quy cách OpenAPI3:
openapi: "3.0.3"
info:
version: 0.0.2
title: BannerX Preview
description: |
Specification for BannerX preview to be implemented by retailer.
In our Banner X creator, we offer a previewer for retailers and advertisers which enables:
- The advertiser to preview their banner’s appearance before launching their campaign
- The advertiser to view their banner in the campaign manager
- The retailer to review the banner before approving it to appear on their website.
- For any retailers wishing to customise the rendering of banner x, you are able to integrate your banner previewer into CitrusAd's platform through a previewer hosted on your site that CitrusAd iframes in the window.
To display the content passed by our platform to your external previewer, you will need to host your own isolated banner previewer on a separate page owned and managed by the retailer. We suggest https://www.<retailer.com>/banner-preview/bannerx.
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. `<strong>`, `<i>` and `<sup>` 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:
`<key1>~<value1>_<key2>~<value2>`
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: `!<hex-code>`
<table>
<thead><td>Character</td><td>Encoded Value</td></thead>
<tr><td>-</td><td>!2D</td></tr>
<tr><td>.</td><td>!2E</td></tr>
<tr><td>_</td><td>!5F</td></tr>
<tr><td>~</td><td>!7E</td></tr>
</table>
The remainder special characters will be URL encoded.
For example. If we have the following field structure:
<table>
<thead><td>Key</td><td>Value</td></thead>
<tr><td>field-one</td><td>Has special chars: ".~_-"</td></tr>
<tr><td>field_two</td><td>#ffffff</td></tr>
</table>
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.
API biểu ngữ X phải có khả năng phản hồi biểu ngữ.
Quy cách này có thể thay đổi - nhà cung cấp dịch vụ tích hợp sẽ được thông báo về mọi thay đổi trước khi triển khai.
Khi người dùng tải trình xem trước trên nền tảng, yêu cầu LẤY sẽ được gửi cùng với một tập hợp các tham số đã xác định được hiển thị trên trình xem trước. Sau đó, yêu cầu sẽ được đặt trong khung nội tuyến trên nền tảng.
Yêu cầu sẽ giống như ví dụ dưới đây:
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
Các trường bổ sung
Tiêu chuẩn nội dung hỗ trợ additionalFields dưới dạng một tập hợp các cặp giá trị khóa. Nội dung này được mã hóa theo cách tùy chỉnh trong chuỗi truy vấn cho người xem trước. Các loại trường được hỗ trợ là:
- lable: giá trị chuỗi
- color: Giá trị màu hex (ví dụ: #0a0a0a)
- select: danh sách liệt kê các chuỗi
Các trường được mã hóa bằng định dạng sau: <key1>~<value1>_<key2>~<value2>
Where:
~: bộ phân tách khóa và giá trị_: bộ phân tách cặp khóa/giá trị
Các ký tự sau được dùng để giữ chỗ và nếu chúng xuất hiện trong khóa hoặc giá trị thì chúng sẽ được mã hóa bằng giá trị đó: !<hex-code>
Ký tự
| Ký tự | Giá trị được mã hóa |
|---|---|
| - | !2D |
| . | !2E |
| _ | !5F |
| ~ | !7E |
Các ký tự đặc biệt còn lại sẽ được mã hóa theo URL.
Ví dụ: Nếu chúng ta có cấu trúc trường sau:
| Khóa | Giá trị |
|---|---|
| field-one | Có các ký tự đặc biệt: ".~_-" |
| field_two | # ffffff |
Nội dung này sẽ được mã hóa trong additionalFields tham số truy vấn như sau: additionalFields=field!2Done~Has%20special%20chars%20%3A%20%22!2E!7E!5F!2D%22_field!5Ftwo~%23ffffff