目次
リセラー向け Criteo REST API
以下はセラーレベルでキャンペーンの入札と予算を管理できるようにする、Criteoリセラープログラム REST API の主な概念についての説明です。
API認証CriteoのREST APIでは、JWTを使用したトークンベースの認証システムを採用しています。CriteoのAPIに呼び出しを行う際には、トークンの引き渡しが必要になります。
トークンを取得するには、パラメーターにclient_idとclient_secretを使用し、/oauth2/tokenエンドポイントにPOSTコールを行う必要があります（「はじめに」のセクションを参照）。
AdvertiserIDの取得AdvertiserIdは、/portfolio/エンドポイントに対しGETコールを実行して取得します。
CamppaignIDの取得CampaignIDは、/sellers/エンドポイントに対しGETコールを実行して取得します。
Criteoリセラープログラムへのセラーの登録セラーを新規に登録するには、かつてCriteoに提出したことのあるカタログフィードで、対象のセラーに正しくフラグを付けておく必要があります。
そのためには、フィード内のセラーの各商品に対し、セラー名カラムをセラー固有の識別子（セラー名）に設定しておく必要があります。
これらの手順を済ませると、上記で説明したセラーのエンドポイント（特に以下）を通じて、Criteoにセラーの予算と入札を送信できるようになります。
- PUT /v1/sellers/bids：セラーのCPCを送信する場合に使用
- POST /v1/sellers/budgets：セラーの予算を送信する場合に使用
Criteoリセラープログラムからセラーのデータを削除
Criteoリセラープログラムからセラーを削除したい場合には、キャンペーン内の該当するセラーを停止することで行えます（「セラーを停止する方法」を参照）。
また、代わりに商品フィードからセラーの商品を削除しても同じ結果が得られます。しかしこの方法の場合、Criteoがフィードとカテゴリーの取り込みを完了した時点でのみ、はじめて有効になります。また、それを追加し直す場合には、新しいフィードとカテゴリーの取り込みが必要となるため、より多くの時間を要します。なお、一度セラーをフィードから削除すると、削除したセラーの統計情報は使用できなくなることにご留意ください。
キャンペーンの開始Criteoリセラープログラムのキャンペーンを開始するには、プログラムに登録されているすべてのセラーの商品が記載されたカタログフィードを、Criteoに提供する必要があります。なお、これらの各商品はセラーフィールドのセラー固有の識別子に関連付けられている必要があります。
キャンペーンは、フィードが取り込まれた時点で自動的に作成されます。
キャンペーンをアクティブ化するためには、予算と入札を設定済みのセラーが1社以上存在する必要があります。これらはPUT /v1/sellers/bidsとPOST /v1/sellers /budgetsエンドポイントをコールして送信できます。
キャンペーン内の特定の、あるいは複数のセラーを停止するには、対象とするセラーの予算を「Inactive」に設定する必要があります。これにより、Criteoのシステムが対象のセラーの商品広告の表示を停止します。
予算を「Inactive」にするには、以下のとおりに/sellers/budgetsエンドポイントに対しPUTコールを実行します。
- PUT /sellers/budgets（status = Inactiveを指定）
お客様側での対応は不要です。Criteoは、すべてのセラーの予算の消化状況を把握・予測しており、セラーが予算を消化し終わったときに、そのキャンペーンを停止します。
予算とCPCの設定特定のセラーの予算とCPCを設定するには、以下のエンドポイントを使用します。
- 入札：初期設定および更新の場合：/sellers/bidsエンドポイントに対しPUTコールを実行
- 予算：
- 初期設定の場合：/v1/sellers/budgets/エンドポイントに対しPOSTコールを実行
- 更新の場合：/v1/sellers/budgets/エンドポイントに対しPUTコールを実行
特定のセラーの予算とCPCを増やすには、/v1/sellers/budgetsおよび/v1/sellers/bidsエンドポイントにPUTコールを実行します。
CPCの減額セラーがCPCを減らしたい場合は、/v1/sellers/bidsエンドポイントに対しPOSTコールを実行します。
予算の減額セラーが予算を減らしたい場合は、まず現在のステータスを「Inactive」に設定します。これで当該日（D）の予算が表示されなくなります。その後、減額した新しい予算を作成します（「予算を新たに作成する方法」セクションを参照）。これはUTC時間の翌日（D+1）から有効になります。
例：
キャンペーンの初日、セラーAがCriteoリセラープログラムに1,000ドルの予算額を設定しました。
キャンペーンの2日後、セラーAの予算はまだ800ドル残っていましたが、セラーAは利用可能な予算を500ドルに減らすことにしました。
この場合、以下のリクエストを送信する必要があります。
- /sellers/budgets/エンドポイントに対しPUTコールを実行
- ステータスを「Inactive」に設定します。
- ここで予算額を正確に設定する必要はありません。ステータスが優先です。
- /sellers/budgets/エンドポイントに対しPOSTコールを実行
- 金額を500に設定します。
- ここでステータスを正確に設定する必要はなく、空欄のままでもかまいません。「Active」になることを想定しています。
予算は以下の2つの条件のいずれかの場合に、新規に作成することができます。
- 当日の予算がない場合
- 当日の予算が非アクティブになっている場合
セラーの予算を新規に作成するには、以下を行います。
- /sellers/budgets/エンドポイントに対しPOSTコールを実行
新しい予算は、以下のいずれかの条件で有効になります。
- 現時点で、当日の予算が存在しない場合
- 明日、非アクティブな当日の予算が存在する場合
まず、新たに更新した予算をセラーに提出してもらってください。
その後は以下の3つのシナリオ別に、それぞれ異なるア
クションが必要になります。
- すでに新しい予算があり、その予算が当初設定した予算よりも小さい場合：
- 「予算／CPCを減らす方法」セクションに記載されたアクションを適用します。
- すでに新しい予算があり、その予算が当初設定した予算よりも大きい場合：
- 「予算／CPCを増やす方法」のセクションに記載されたアクションを適用します。
- 新しい／正しい予算がない場合：
- 「セラーを削除する方法」セクションに記載されたアクションを適用します。
まず、更新したCPCをセラーに提出してもらう必要があります。その後、/sellers/bids/エンドポイントに対しPUTコールを行い、更新済みの入札を設定します。
セラーがプラットフォーム上の名前を変更した場合CriteoのAPIは基本的に、sellerNameをもとに入札と予算を管理します。そのため、セラーの名前が変更されると、Criteo のシステムに新しいエントリが自動的に作成され、以前の名前には関連付けられません。
つまり、セラーが貴社のプラットフォームで名前を変更した場合には、以下の操作を行う必要があります。
- お客様の商品フィードを、新しいsellerNameで更新します。
- CriteoにPUT /v1/sellers/bidsとPOST /v1/sellers/budgetsの指示を送信し、セラーの入札と予算を初期化します。
Criteoリセラープログラムのキャンペーンにおいて、特定のセラーの支出済み予算は、/v1/sellersエンドポイントに対しGETコールを実行することで確認できます。この情報はspentAmountとして入手できます。
セラーの残り予算の分析Criteoリセラープログラムのキャンペーンにおいて、特定のセラーの支出済み予算は、/v1/sellersエンドポイントに対しGETコールを行うことで確認できます。この情報はremainingAmountとして入手できます。
レポート作成/v1/sellers/statsエンドポイントに対しPOSTコールを実行して取得できます。アクセスできるのはセラーレベルのインプレッション、クリック数、コストのみとなり、最高で日単位の粒度で取得できます。
最大3つのディメンションを使用できますが、セラーのディメンションを必ず含める必要があります。
使用可能なディメンション：
- AdvertiserID
- campaignID
- セラー（必須）
- 年
- 週
- 日
使用可能なメトリック：
- 表示数
- clicks
- AdvertiserCost