Integrating your banner X previewer

In CitrusAd’s 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.

CitrusAd embeds a default previewer in the CitrusAd platform that displays to the advertiser and retailer (for retailers that integrate CitrusAd's banner x offering exactly as it is provided). For any retailers wishing to customise the rendering of banners, you are able to integrate your banner previewer into CitrusAd's platform.

This means you’ll be free to make changes to how your banners are rendered without any dependency on CitrusAd. You are also free to update how images and text served by CitrusAd are rendered on your live site. Any changes made to banners on the live site should be instantly reflected in the CitrusAd platform via your external previewer.

12001200

External previewer image

How to integrate the preview specification

To display the content passed by CitrusAd 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.

The OpenAPI3 spec can be seen below:

openapi: "3.0.0"
info:
  version: 0.0.1
  title: BannerX Preview
  license:
    name: MIT
paths:
  '/banner-preview':
    get:
      summary: Render a preview of a bannerX
      operationId: getBannerXPreview
      tags:
        - campaign
      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:
            uat:
              value: "bd59be89-b13f-440f-a57e-0e5a481bec8b"
              summary: "example UAT 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:
            uat:
              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:
            uat:
              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:
            uat:
              value: "Juicy apples!"
              summary: "banner heading text"
          required: false
          schema:
            type: string
        - name: "bannerText"
          in: query
          description: Banner text to insert into the banner rendering.
          required: false
          examples:
            uat:
              value: "Citrus UAT Banner"
              summary: "banner text"
          schema:
            type: string
        - name: "bannerTextColour"
          in: query
          description: Banner text colour in RGB HEX format.
          examples:
            uat:
              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:
            uat:
              value: true
              summary: "banner CTA enabled flag"
          required: false
          schema:
            type: boolean
        - name: "ctaLink"
          in: query
          description: Link for Call-To-Action element.
          examples:
            uat:
              value: "https://www.retailer.com/promo/6ru0GM5"
              summary: "banner CTA link"
          required: false
          schema:
            type: string
        - name: "backgroundColour"
          in: query
          description: Banner text colour in RGB HEX format.
          examples:
            uat:
              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:
            uat:
              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:
            uat:
              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:
            uat:
              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:
            uat:
              value: "New flavour chips"
              summary: "hero image alt text"
          required: false
          schema:
            type: string
        - name: "secondaryHeroImage"
          in: query
          description: Secondary hero image URL.
          examples:
            uat:
              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:
            uat:
              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:
            uat:
              value: "BLOCK"
              summary: "secondary hero image mode"
          required: false
          schema:
            type: string
            enum:
              - UNDEFINED
              - BLOCK
              - LANDSCAPE
        - 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:
            uat:
              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.

🚧

Banners must remain within the capabilities of the Banner X API response.

📘

This specification is subject to change - integrators will be notified of any change in advance of implementation.

When a user loads the previewer in the CitrusAd platform, a GET request is made with a set of defined parameters that are rendered on your previewer. This is then iframed within the CitrusAd platform.

The request will look similar to the example below:

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&gtins=7459770&gtins=59398&gtins=7895365