파트너 API

배너 X 미리보기 통합

CitrusAd의 Banner X 작성자에서는 소매업체 및 광고주에 대한 미리보기를 제공하며 이를 통해 다음 기능을 지원합니다.

  • 광고주가 캠페인을 시작하기 전에 배너의 모양을 미리 볼 수 있음
  • 광고주가 캠페인 관리자에서 배너를 볼 수 있음
  • 소매업체가 웹사이트에 배너를 게시하는 것을 승인하기 전에 배너를 검토할 수 있음

배너 x의 렌더링을 맞춤 설정하려는 소매업체의 경우, 사이트에서 호스팅되는 배너 미리보기를 통해 CitrusAd가 창에 아이프레임으로 삽입하는 배너 미리보기를 CitrusAd 플랫폼에 통합할 수 있습니다.

🚧

이것은 호스팅된 소매업체입니다

소매업체는 자신이 소유하고 관리하는 URL이나 링크에서 이것을 호스팅해야 합니다.

따라서 사이트와 디자인이 변경될 때 이를 유연하게 관리하고 업데이트할 수 있으며, 변경 시 CitrusAd를 사용하지 않아도 됩니다.

일반적으로 retailer.com/banner-previewer와 같은 숨겨진 URL의 사이트에 호스팅하는 것이 좋습니다. 그러나 호스팅 위치는 사용자가 결정해야 합니다.

또한 실시간 사이트에서 CitrusAd가 제공하는 이미지와 텍스트가 렌더링되는 방법을 자유롭게 업데이트할 수 있습니다. 실시간 사이트에서 배너에 적용된 변경사항은 외부의 미리보기를 통해 CitrusAd 플랫폼에서 즉시 반영되어야 합니다.

1200

외부 미리보기 이미지

미리보기 사양을 통합하는 방법

CitrusAd 광고를 통해 전달된 콘텐츠를 외부 미리보기에 표시하려면 소매업체가 소유하고 관리하는 별도의 페이지에서 자체 분리된 배너 미리보기를 호스팅해야 합니다. 다음을 권장합니다. https://www.<retailer.com>/banner-preview/bannerx.

OpenAPI3의 스펙은 아래에서 확인할 수 있습니다.

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.

🚧

배너는 배너 X API 응답 기능 내에 있어야 합니다.

📘

이러한 사양은 변경될 수 있으며 통합자는 사양이 변경될 때마다 사전에 이를 통보받습니다.

사용자가 CitrusAd 플랫폼에서 미리보기를 로드하면 미리보기 상에서 렌더링되는 정의된 파라미터 세트를 통해 GET 요청이 이루어집니다. 그런 다음 이를 CitrusAd 플랫폼 내에서 아이프레임화 합니다.

요청은 아래 예시와 비슷하게 이루어집니다. 

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