パートナーAPI

統合の要件

概要

この統合の一環として、以下の操作を実行する必要があります。

  1. クロスセルカテゴリプレースメントに追加の広告リクエストを実装します。
    1. これには、サイト上に広告を配置してレンダリングする作業や、クリック数やインプレッション数を報告する作業が含まれます。
    2. 注文は、標準統合の一部としてCitrusAdに提供される必要があります。
  2. カテゴリIDをCitrusAdと同期する場合、filterMappingAPIを使用して、UIカテゴリ選択に人間が読める値を指定する必要があります。
    1. これは、名前ではなくカテゴリIDを使用して統合されている場合にのみ適用されます。(例えば、広告をリクエストする場合、フィルタが category:123j-dsef-er で広告をリクエストしている可能性があります（ category:Milk
  3. (推奨) - カテゴリのクロスセルマッピングを同期すると、承認を自動化し、キャンペーン管理の負荷を軽減できます。

広告リクエストとサイト統合

広告リクエスト

カテゴリクロスセルには独立したプレースメントが必要なため、カテゴリクロスセルを統合する広告タイプごとに追加の広告リクエストを統合する必要があります。

リクエストの形式は、以下に示すクロスセルカテゴリの広告リクエストと一致しなくてはなりません。

インプレッション数とクリック数の報告

広告リクエストをいったん統合したら、表示された各広告のクリック数とインプレッション数を正しく報告できているか確認する必要もあります。インプレッション数とクリック数の報告を必ずお読みください。

注文の報告

通常、ほとんどの統合では、標準統合に従ってすべての注文情報がCitrusAdに報告されます。注文データに従って、すべての注文がCitrusAdに正しく報告されているかを確認する必要があります。

フィルタマッピング

フィルターマッピングエンドポイントを使用すると、カテゴリIDを人間が読み取れる値にマッピングできます。この場合、UIがユーザーに値を表示するときにカテゴリIDを同期する場合に必要です。

📘

商品カタログ内の人間が読めるカテゴリをCitrusAdと同期する場合、この手順は必要ありません。

ユーザーは category:12345-abcde が何であるのか理解できません。filterMapping APIを使用すると、サイト上の関連するカテゴリ名に値をマッピングできます。 category:Pantry.

この情報を同期させるファイルベースの方法はなく、filterMappingAPIを介して行う必要があります。

🚧

サイトに追加のカテゴリを作成するときは、カテゴリの更新にfilterMapping APIが使用されていることを確認する必要があります。

カテゴリのクロスセルマッピング(推奨)

このタイプのプレースメントを統合する場合は、どのカテゴリが相互にターゲティングできるかのマッピングを提供することを強くお勧めします。これにより、最初の統合作業後の業務を効率化することができます。広告主のエクスペリエンスは、すでに選択が許可されているカテゴリのみを許可するよう合理化されています。

さらに、クロスセルマッピングが提供されている場合、クロスセルカテゴリキャンペーンの自動承認を設定することもできます。

統合方法

  • crossSellCategoryAPIを使用して、必要なマッピングを作成および管理できます。
  • あるいは、以下に示す形式で、CitrusAdがホストするGCSバケットにTSVファイルを提供することもできます。

API統合

必要な情報はすべてcrossSellCategoryAPIリファレンスで確認できます。

ファイル統合

ファイルごとに統合する場合、CitrusAdはカタログごとにファイルを必要とします。そのカテゴリ間で相互にターゲットを設定できます。

ファイル内の各行は、カテゴリの1つのマッピングと、それがターゲットにできるカテゴリを示しています。各マッピングは一方向です (チョコレート -> ミルクを同期すると、チョコレート製品がミルクカテゴリに表示されます。乳製品をチョコレート上に表示できるようにする必要があり、追加の行が必要な場合)。

以下の仕様に準拠したTSV形式のデータフィードが必要です。

列名必須データタイプ説明例
category必須テキストこれは、宣伝される商品のカテゴリを識別する一意のカテゴリIDです。category:cookies
cross_category_id必須テキストこれは、category_idの製品をクロスセルできる適格なカテゴリを識別する一意のカテゴリIDです。category:milk

追加のファイル仕様は次のとおりです。

  • TSVファイルのみがサポートされている
  • TSVはCRLFではなくLFでなくてはならない
  • TSVはUTF-8でエンコードされている必要があり、どのタイプでもフィードが失敗する原因になる
  • 以下の命名規則が必要: ^cross_sell_category.*.tsv$

スニペットの例は次のとおりです。

カテゴリcross_category_id
category:cookiescategory:milk
category:cookiescategory:chocolate
category:milkcategory:cookies

上記のスニペットにより、クッキーカテゴリをミルクカテゴリとチョコレートカテゴリにクロスセルできるようになります。ミルクカテゴリをクッキーカテゴリにクロスセルできます。チョコレートカテゴリをターゲットにすることはできますが、他のカテゴリをターゲットにはできません。

❗️

各行は一意のマッピングの組み合わせです

一意のクロスセルカテゴリマッピングごとに一意の行を同期する必要があります。単一行内の複数のcross_category_idを同期しようとすると、ファイルの取り込みは失敗します。

機能の有効化プロセス

検索用語候補フィードの同期を開始する準備ができたら、CitrusAdがファイルをドロップするためのGCSバケットを設定します。

この機能は、GCSバケットでのみサポートされています。AWS/Azure/その他の外部バケットはサポートされていません。

テクニカルアカウントマネージャーが、この機能の有効化についてご案内します。CitrusAdのプラットフォーム運用チームは設定を行う必要があるため、有効化にはさらに時間がかかることにご注意ください。