API para socios

Integración de vista previa de banner X

En el creador de Banner X de CitrusAd, ofrecemos una vista previa para minoristas y anunciantes que permite:

  • Que el anunciante pueda previsualizar la apariencia de su banner antes de lanzar su campaña
  • Que el anunciante pueda ver su banner en el administrador de campañas
  • Que el minorista pueda revisar el banner antes de aprobarlo para que aparezca en su sitio web.

Para cualquier minorista que desee personalizar la representación del banner x, puede integrar su previsualizador de banners en la plataforma de CitrusAd a través de un previsualizador alojado en su sitio web que CitrusAd enmarca en la ventana.

🚧

Este es un minorista alojado

Como minorista, tendrá que alojarlo en una URL o enlace de su propiedad y gestión.

Esto le ofrece total flexibilidad para gestionar y actualizar a medida que su sitio y su diseño cambian, sin crear dependencia de CitrusAd cuando desee realizar cambios.

Por lo general, recomendamos alojarlo en su sitio en una URL oculta como retailer.com/banner-previewer, pero dependerá de usted decidir dónde.

También puede actualizar la forma en que se renderizan las imágenes y el texto que muestra CitrusAd en su sitio activo. Cualquier cambio realizado en los banners en el sitio activo debe reflejarse instantáneamente en la plataforma de CitrusAd a través de su vista previa externa.

1200

Imagen de vista previa externa

Cómo integrar la especificación de vista previa

Para mostrar el contenido transferido por CitrusAd a su previsualizador externo, tendrá que alojar su propio previsualizador de banners aislado en una página independiente propiedad del minorista y gestionada por este. Sugerimos https://www.<retailer.com>/banner-preview/bannerx.

La especificación OpenAPI3 se puede ver a continuación:

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.

🚧

Los banners deben permanecer dentro de las capacidades de la respuesta de la API de Banner X.

📘

Esta especificación está sujeta a cambios. Se notificará a los integradores sobre cualquier cambio antes de su aplicación.

Cuando un usuario carga la vista previa en la plataforma de CitrusAd, se realiza una solicitud GET con un conjunto de parámetros definidos que se renderizan en la vista previa. Esto luego se enmarca dentro de la plataforma de CitrusAd.

La solicitud será similar al ejemplo que aparece a continuación: 

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