パートナーAPI

ブランドページを依頼する

ブランドページのエンドポイント

ブランドページプラットフォームは、スタンドアロンのURLと広告生成エンドポイントへのパスを使用します。テクニカルアカウントマネージャーは、サンドボックス環境および本番環境のベースURLを提供します。

Authorization

ブランドページツールの認証はベアラー認証です。テクニカルアカウントマネージャーは、サンドボックス環境および本番環境のベアラートークンを提供できます。

ヘッダーのトークンを次のように送信する必要があります。 header 'Authorization: Bearer ${apiKey}

リクエスト

ブランドページをリクエストするには、CitrusAd に GET リクエストを送信します。 brand-page要求している URL を持つエンドポイント

curl --location --request GET '${URL}/api/v1/brand-page:static?url=${url}&retailer=${retailer}' \
--header 'Authorization: Bearer ${apiKey}

🚧

URL クエリパラメータのサニタイズ

広告をリクエストするときは、CitrusAd に送信されるパラメータからサイトに関連するクエリパラメータを削除する必要があります。

CitrusAdプラットフォーム内では、このURLを使用して、リクエストされている正確なページURLを取得します。以下となります。 https\:www.retailer.com/brand/lollipops-brandただし、追加のクエリパラメータが指定されている場合は異なります。

レスポンス

ブランドページの構成に応じて、セグメントのレスポンスは、統合されたセグメントとブランドページのテンプレートの両方によって異なります。

カスタマイズ機能を確認したい場合は、 ハイレベル構造 ページをご覧ください。

レスポンスコンポーネント

コンテナ

コンテナはブランドページのレスポンス全体の情報を提供し、セグメントレスポンスが保持されるオブジェクトのデータ配列も備えています。

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
  ]
}

先ほどの data 配列には、ブランドページの設定に従ってセグメントが設定されます。セグメントの形式については、以下で詳しく説明しています。

セグメント

ブランドページ製品はカスタマイズできるため、受け取る正確なレスポンスは設定によって異なります。すべてのセグメントには、 id と nameに加えて、セグメント固有のプロパティがあります。

バナーセグメント

以下のようなオブジェクトが data 配列の各セグメントにはあります。

📘

レスポンスに含まれるバナー x 固有の属性は一例に過ぎません。レスポンスの値はテンプレートごとに設定され、 backgroundImage、 brandLogo、など、または必要に応じてカスタマイズできます。

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
    	  "headingText": "Banner For MasterFoods Beef Stroganoff with Shop Now button",
    	  "bannerText": "<strong>The Perfect Mid-Week Dinner</strong>",
    	  "bannerTextColour": "#fff",
   		  "heroImage": "https://storage.googleapis.com/assets-images/coke/2853856c8644",
  	    "heroImageAltText": "<i>Picture of the Dolmio Pasta Sauce</i>",
	      "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
	      "secondaryHeroImageAltText": "Milo Logo",
	      "secondaryHeroMode": "landscape",
	      "backgroundColour": "895b5b",
	      "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
	      "backgroundImagePosition": "FILL",
  	    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada"
}

バナーセグメントでできることについての詳細は、ハイレベル構造を参照してください。

コンテンツセグメント

以下のようなオブジェクトが data 配列の各セグメントにはあります。

📘

heroText、heroTextColour、および heroSubText は、小売業者の例です。各フィールドには、関連するフィールドタイプの名前を付けることができます。例： paragraphText.

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
        "heroText": "<i>What a way to start your week</i>",
        "heroTextColour": "#000000",
        "heroSubText": "<i>What a way to start your week</i>",
}

コンテンツセグメントでできることについての詳細は、 ハイレベル構造を参照してください。

製品セグメント

以下のようなオブジェクトが data 配列の各セグメントにはあります。

📘

このレスポンス形式は固定されており、カスタマイズの対象にはなりません

 {
      "id":  "988dc393-a37a-421c-9b08-25f0f9e575f8",
      "name": "my-products",
      "productSelection": [
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 3,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 2,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 1,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        }
      ]
    }

📘

製品情報

標準的な商品広告の統合と同様、CitrusAd は名前、価格、画像などの商品属性は提供しません。これは、小売業者のインフラストラクチャ上の内部製品情報サーバー（または同様のもの）から取得する必要があります。

これは統合の追加作業となる反面、価格情報の更新や変更時にCitrusに依存しなくて済みます。さらには、特別価格や20%オフといった自動グラフィックもCitrusAdに依存することがなくなります。

製品セグメントでできることについての詳細は、 ハイレベル構造 を参照してください。

レスポンスの解釈

レスポンスでは、各セグメントに id と nameがあり、これらはテンプレート内のセグメントに固有のものになります。これらを使用して、バナーのタイプやコンテンツのタイプなど、さまざまなタイプのコンポーネントを識別し、挿入する場所に揃えることができます。

レスポンスの例

以下は、1 つのバナー、1 つのコンテンツ、および 1 つの製品セグメントを含むテンプレートに対するブランドページのレスポンス例です。

📘

CUSTOM_ID_N といった小売業者が定義したIDの例です。 paragraphText.

レスポンス

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_ID_1": "string",
      "CUSTOM_ID_2": "string",
      "CUSTOM_ID_3": "string"
    },
    {
      "id":  "string",
      "name": "string",
      "productSelection": [
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        }
      ]
    },
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_TEXT_FIELD_ID_1": "VALUE",
      "CUSTOM_COLOUR_FIELD_ID_1": "VALUE",
      "CUSTOM_TEXT_FIELD_ID_2": "VALUE",
    }
  ]
}

他のテンプレートや使用例はブランドページのテンプレート例 をご覧ください。