ログイン

サポートセンター

実装と運用のサポートコンテンツをご利用いただけます。

サポートセンター. 実装と運用のサポートコンテンツをご利用いただけます。

CriteoリセラープログラムAPIガイド V2.0

 

ガイドの変更履歴

バージョン

リリース日

変更

V1.0 2017年11月 初版リリース
V1.1 2018年3月 レポートのインプレッションレベルをガイドに追加
V1.2 2018年9月 新しいフィルタリングオプションをガイドに追加
V2.0 2018年9月

クライアントが体系化して理解できるように、APIガイドV2のプレビューを提供。本ガイドには、日単位の予算に関する新機能についての詳細が追加されました。

 

 

本書について

このドキュメントでは、Criteo REST APIとの連携方法を説明しています。Criteoの新しいAPI V2を使用することで、お客様はセラーに代わってCriteoリセラープログラムのキャンペーンを実施できるようになります。本ドキュメントでは、API V2 で変更が必要になる部分についても説明しています。

以下はお客様がセラーに代わり実行できる主な機能です。
  • 予算の作成と更新
  • 入札(CPC)の作成と更新
  • セラーの停止
  • セラーの統計情報の取得

はじめに

CriteoのREST APIを使用する際には、マネージメントセンターで新しいAPIユーザを作成しておく必要があります。このプラットフォームには、https://marketing.criteo.com/からアクセスすることができます。

ログインして以下の操作を行います:

  • [設定(Setup)] > [ユーザ(Users)] をクリックします。

 

 

  • 次に、[APIユーザの作成(CREATE API USER)] をクリックします。

 

  • 連絡先のEメールアドレスを入力し、以下のいずれかの役割を選択します:閲覧のみ(View Only)ビジネスマネージャー(Business Manager)ファイナンシャルマネージャー(Financial Manager)。APIを利用するためには、ビジネスマネージャーを選択します。閲覧のみおよびファイナンシャルマネージャーの権限には、APIを使ったデータの入出力のための十分な権限がありません。
  • 設定を完了したら、[ユーザを追加する(Add User)] をクリックします。確認メッセージ、お客様の [クライアントID(Client ID)] および [クライアントの機密情報(Client Secret)] が表示されます。これらの情報はAPI にリクエストをポストする際に必要になるため、大切に保管してください。

currency

以下を含め、Criteo REST APIのすべての金額はお客様の現地通貨で表示されます:

  • パフォーマンス値(COS やコストなど)
  • 予算と入札

お客様の現地通貨は、マネージメントセンターで確認できます。[設定(Setup)] > [ユーザ(Users)] に進み、該当するユーザを選択してください。

時間帯

Criteo REST APIに表示される日付はすべて、協定世界時刻(UTC)となります。

データの更新

残り予算と統計情報の表示はリアルタイムではありません。最大で数時間の遅れが生じる可能性があります。そのため、セラーに予算が残っていても停止状態になっている場合があります。この場合、セラーの広告は表示されませんが、データ処理が進行中のため残予算は減少していきます。

APIの使用に関する推奨事項

予算または入札内容をまとめて更新する場合、多数のコールを個別に実行すると処理速度が低下する恐れがあるため、別々のバッチAPIコールとして実行してください。

1つは入札のコール、もう一方は予算のコールとして実行します。いずれのコールについても、対象となるキャンペーンごとに正しい入札と、特定の/複数のキャンペーンに対する予算が含まれるようにします。

例:セラー10社の入札と予算を設定する場合、セラーキャンペーンのエンドポイントに対して1つのAPIコール、予算エンドポイントに対して1つのAPIコールを行い、いずれにも該当するセラーが希望する入札金額と予算額を含むようにすることを推奨します。

技術的要素

すべてのテクニカルコンポーネントとエンドポイントが、今回のV2ドキュメントで刷新されています。比較にあたっては、V1のSwaggerをこちらからご確認いただけます:

https://api.criteo.com/marketing/swagger 

このSwaggerには、以下のエンドポイントがあります。

  • Authentication(認証):トークンを取得できます。セキュリティ上の理由から、トークンの有効期限は5分間に制限されています。
  • Portfolio(ポートフォリオ):AdvertiserIdおよびAdvertiser Nameなどの基本情報を取得することができます。
  • Sellers
    • GET /v2/crp/sellers:セラーの基本情報の取得
    • POST /v2/crp/statistics:基本的なキャンペーン統計情報の取得
  • 予算
    • GET /v2/crp/budgets:予算別のステータスおよび残高の取得
    • POST /v2/crp/budgets:セラー別に予算を作成
    • PUT /v2/crp/budgets:セラー別に予算を更新
  • Sellers-campaign
    • GET/v2/crp/seller-campaign:キャンペーンにおけるセラーの入札に関する情報の取得
    • PUT /v2/crp/seller-campaigns:キャンペーンに対する入札(CPC)をセラーに提供

SellersとSellers-campaignは、カタログのインポートによって自動的に作成されるため、POSTコールは提供していないことにご注意ください。

例:このSwaggerは、Criteoの本番環境にリンクしています。そのため、ここで適用されたテストは実際のキャンペーンに影響を与えることにご注意ください。

APIの概要

以下はセラーレベルでキャンペーンの入札と予算を管理できるようにする、Criteoリセラープログラム REST API の主な概念についての説明です。

最初のステップ

APIで認証を受けるには、どうすればよいですか?

Criteoでは、JWTを使ってREST APIに対してトークンベースの認証システムを提供しています。CriteoのAPIの呼び出しを行う際には、トークンの引き渡しが必要になります。

トークンを取得するためには、パラメーターにclient_idとclient_secretを使用して、/oauth2/tokenエンドポイントに対してPOSTコールを行う必要があります(「はじめに」のセクションを参照)。

注:各トークンの有効期限は5分間です。トークンの有効期限が切れると、HTTPステータスコード:401が表示されます。

Advertise IDを取得するにはどうすればよいですか?

AdvertiserIdは、/portfolio/エンドポイントに対しGETコールを実行して取得します。

Catalog IDを取得するにはどうすればよいですか?

/v2/crp/sellers/エンドポイントに対してGETコールを行い、CatagogIDを取得します。

Campaign IDを取得するにはどうすればよいですか?

/v2/crp/seller-campaignsエンドポイントにGETコールを行い、CampaignIDを取得します。

セラーの管理

Criteoリセラープログラムにセラーを登録するためには、どうすればよいですか?

ステップ1:セラーを新規に登録する際には、以前Criteoと共有した商品フィードの対象セラーに適切な形でフラグが設定されている必要があります。

そのためには、フィードで提供される各商品のセラー名を表すセラー固有の識別子を、セラー名カラム (seller name colum) に設定しておく必要があります。

ヒント:フィード経由で有効な商品をCriteoに送信するとセラーも有効になります。

その時点でセラーが登録され、すべてのCRPキャンペーンを対象とするseller-campaignsが作成されます。

ステップ2:GET /v2/crp/seller-campaignsで seller IDとseller-campaign IDを取得します。

ステップ3:上記で説明したセラーエンドポイントによって、Criteoにセラーの予算と入札を送れるようになります。

  • 特にPOST /v2/crp/budgets は、セラーの予算を送り、複数のキャンペーンで共有できるようになります。
  • PUT /v2/crp/seller-campaignsは、seller-campaign別にセラーのCPCを提供します。

ヒント:セラーのエンドポイントにCriteo Reseller Program catalog id(catalogId)をパラメーターとして指定し、GETをコールすることで、セラーの一覧とそのステータス(有効/無効)を取得することができます。

Criteoリセラープログラムからセラーのデータを削除するには、どうすればよいですか?

Criteoリセラープログラムからセラーを削除する場合は、PUT /v2/crp/budgets with status = STOPPEDを実行して、該当するセラーの予算を停止する必要があります。

また、代わりに商品フィードからセラーの商品を削除しても同じ結果が得られます。しかし、この方法を選択した場合、Criteoがフィードとセラーの取り込みを完了した時点でのみ削除が有効になります。また、セラーを追加し直す場合には、新しいフィードとセラーの取り込みが必要となるため、より多くの時間を費やすことになります。そのため、Criteoではこの方法は推奨していません。

フィードからセラーを削除した場合でも、そのセラーの統計情報には影響しません。

キャンペーンの管理

キャンペーンを開始するためにはどうすればよいですか?

Criteoリセラープログラムのキャンペーンを開始する前に、プログラムに登録されているすべてのセラーの商品を含む商品フィードをCriteoに提供する必要があります。なお、各商品のセラーのフィールドにはセラー固有の識別子が設定されている必要があります。キャンペーンは、フィードが取り込まれた時点で自動的に作成されます。

キャンペーンを有効化するためには、予算と入札を設定したセラーが少なくとも1つ必要です。しかし、本来CRPキャンペーンは、数百、数千規模のセラーを対象としたものであり、こうした少数のセラーでキャンペーンを開始することはお勧めしていません。

ヒント:すでにCriteoをご利用に場合、次のような選択肢もあります:

  • 推奨:現在のフィードのセラーのフィールドに、セラーの情報を追加します(現在、カテゴリーを3つ使用していない場合)。
  • あるいは、すでにCriteoに提供しているフィードを複製します(セラーのフィールドでセラー固有の識別子が設定されていることを確認してください)。
    • この場合、キャンペーンのご請求については別途ご相談ください。理想的には、現在の請求にこの新しいCRPキャンペーンを統合することが推奨されます。

キャンペーンは、フィードが取り込まれた時点で自動的に作成されます。キャンペーンを有効化するためには、予算と入札を設定したセラーが少なくとも1つ必要です。しかし、本来CRPキャンペーンは、数百、数千規模のセラーを対象としたものであり、こうした少数のセラーでキャンペーンを開始することはお勧めしていません。

これらはPOST /v2/crp/budgets and put /v2/crp/seller-campaignsで送ることができます。

キャンペーンを停止するためにはどうすればよいですか?

Criteoリセラープログラムのキャンペーン全体(全セラーのキャンペーン)を停止するには、担当のアカウントマネージャーに連絡してください。

セラーを停止するためにはどうすればよいですか?

キャンペーン内の特定の、または複数のセラーを停止する場合には、対象とするセラーの予算を [停止(STOPPED)] に設定する必要があります。

これにより、Criteoのシステムが対象のセラーの商品広告の表示を停止します。

予算を [停止(STOPPED)] 状態にするには、 /sellers/budgetsエンドポイントに、PUT /v2/crp/budgets with status = STOPPEDを実行します。

注:[停止(STOPPED)] 状態にあるセラー予算を、再び有効化することはできません。[停止(STOPPED)] 状態にあるセラーを再び有効化するには、新規に予算を作成する必要があります(「予算を新たに作成」セクションを参照)。

予算を停止した場合でも、統計情報のアップロード完了までに数時間を要するケースがあるため、停止した予算が消化されているように見えることがあります。例えば、$10で予算を停止した場合、広告の表示自体は停止しますが、支払いが残っている可能性があります。この場合、最終的に$9.50などで終了する場合があるかもしれません。

セラーの予算が残りわずかになった場合、どうすればよいですか?

お客様側での対応は不要です。Criteoは、すべてのセラーの予算の消化状況を把握・予測しており、セラーが予算を消化し終わったときに、そのキャンペーンを停止します。

予算やCPCを設定するためにはどうすればよいですか?

特定のセラーの予算とCPCを設定する際には、以下のエンドポイントを使用します。

  • 予算:
    • 初期設定の場合:/v2/crp/budgetエンドポイントに対してPOSTコールを実行
    • 更新の場合:/v2/crp/budgetエンドポイントに対してPUTコールを実行
  • CPC:初期設定および更新の場合:/v2/crp/seller-campaignエンドポイントに対してPUTコールを実行

予算またはCPCを増額するにはどうすればよいですか?

特定のセラーの予算やCPCを増額する際には、/v2/crp/budgetまたはv2/crp/seller-campaignエンドポイントに対してPUTコールを実行します。

予算またはCPCを減額するにはどうすればよいですか?

セラーがCPCを減額したい場合は、v2/crp/seller-campaignエンドポイントに対してPOSTコールを実行します。

予算を減額するにはどうすればよいですか?

セラーが予算を減額したい場合は、まず現在のステータスを [停止(STOPPED)] に設定します。これで当該日(D)の予算を使用した広告が表示されなくなります。その後、減額した新しい予算を作成します(「予算を新たに作成する方法」セクションを参照)。これはUTC時間の翌日(D+1)から有効になります。

例:

0日目: セラーAが予算を1,000ドルに初期設定。

2日目: セラーAの予算はまだ800ドル残っているが、利用可能な予算を500ドルに減額。

この場合、以下のリクエストを送信する必要があります。

  • /v2/crp/budgetsエンドポイントに対してPUTコールを実行
    • ステータスを [停止(STOPPED)] に設定
    • ここで予算額を正確に設定する必要はありません。ステータスが優先です。
  • /v2/crp/budgetsエンドポイントに対してPOSTコールを実行
    • 金額を500に設定します。
    • ここでステータスを正確に設定する必要はなく、空欄のままでもかまいません。「Active」になることを想定しています。

重要:減額された予算は即座に反映され、以下の影響が発生します:

  • セラーの当日の残りのキャンペーンは、直ちに停止されます。
  • セラーは翌日の午前0時(UTC)に、新しく設定された予算でキャンペーンを再開します。

予算を新たに作成するにはどうすればよいですか?

予算は以下の2つのいずれかの条件を満たす場合、新規に作成することができます。

  • 該当するセラーに当日の予算が何も設定されていない場合。(予算を重複させることはできません)
  • 該当するセラーの予算が [すべて消化済み(DEPLETED)] の状態にある場合。

セラーの予算を新規に作成するには、以下を実行します。

  • /v2/crp/budgetsエンドポイントに対してPOSTコールを実行

新しい予算は、以下のいずれかの条件で有効になります。

  • セラーに予算が設定されていない場合は当日
  • 予算がすでに存在する場合は翌日

セラーが誤った予算を設定しました。修正するにはどうすればよいですか?

まず、更新済みの予算をセラーに提出してもらう必要があります。その後、以下の3つのシナリオ別に異なる対応が必要となります。

  • すでに新しい予算があり、その予算が当初設定した予算よりも小さい場合:
    • 「予算またはCPCを減額するにはどうすればよいですか?」のセクションに記載された内容を実行します。
  • すでに新しい予算があり、その予算が当初設定した予算よりも大きい場合:
    • 「予算またはCPCを増額するにはどうすればよいですか?」のセクションに記載された内容を実行します。
  • 新しい/正しい予算がない場合:
    • 「セラーを削除する方法」のセクションに記載された内容を実行します。

セラーが誤った入札を設定しました。修正するにはどうすればよいですか?

まず、更新済みのCPCをセラーに提出してもらう必要があります。その後、/v2/crp/seller-campaignsエンドポイントに対してPUTコールを実行し、更新済みの入札を設定します。

セラーがCriteoのプラットフォーム上の名前を変更したらどうなりますか?

CriteoのAPIは基本的に、sellerNameをもとに入札と予算を管理します。そのため、セラーの名前が変更されると、Criteo のシステムに新しいエントリが自動的に作成され、以前の名前には関連付けられません。
つまり、セラーが貴社のプラットフォームで名前を変更した場合には、以下の操作を行う必要があります。

  • お客様の商品フィードを、新しいsellerNameで更新します。
  • CriteoにPUT /v2/crp/seller-campaignsおよびPOST /v2/crp/budgetsを送信し、セラーの入札と予算を初期化します。

注:以前のsellerNameの統計情報は、統計のエンドポイントから取得することができます。

セラーが消化した予算はどのように確認できますか?

特定のセラーの消化済みの予算を確認するには、Criteoリセラープログラムキャンペーンでv2/crp/budgetsに対してGETコールを実行します。この情報はspentAmountとして入手することができます。

セラーの残予算はどのように確認できますか?

Criteoリセラープログラムのキャンペーンにおいて、特定のセラーの消化済み予算は、/v2/sellersエンドポイントに対してGETコールを行うことで確認できます。

この情報はremainingAmountとして入手することができます。

予算にはどのようなステータスがありますか?

  • 実行中(Running)
  • 消化済み(Depleted):予算をすべて消化し、セラーの広告表示が停止された状態
  • 停止(Stopped):お客様が手動で該当するセラーを停止した状態
  • 終了(Ended):この予算の終了日を指定していて、その日が過ぎた状態
  • スケジュール設定済み(Scheduled): 将来の開始日が指定された状態

予算の消化が後日開始されるように設定することはできますか?

はい。開始日を指定することで、予算消化を後日開始されるように設定できます。予算は午前0時(GMT)から開始されます。

予算の終了日を設定することは可能ですか?

はい。設定した場合の終了時刻は、設定日の23時59分(GMT)となります。翌日、予算のステータスが [すべて消化済み(DEPLETED)] に自動的に設定されます。

日単位の予算を設定できますか?

現時点ではできません。しかし、将来的にbudget type = DAILYとして金額を設定できるようにする予定です。本機能は2019年の第1四半期を目標にリリース予定ですが、リリースを確約するものではないため、最新情報をご確認ください。

セラーの予算に関するコール結果をフィルタリングすることはできますか?

はい。以下のフィルターをご利用いただけます。

  • /v2/crp/sellers
    • sellersエンドポイント用:ステータス [有効(Available)/ 無効(NotAvailable)] 、セラーidでフィルタリングできます。
  • /v2/crp/seller-campaigns
    • seller-campaignsエンドポイント用:キャンペーンidおよびセラーidでフィルタリングできます。
  • /v2/crp/budgets
    • 予算エンドポイント:ステータス別

レポート作成

/v2/crp/statisticsエンドポイントに対してPOSTコールを実行することができます。アクセスできるのはセラーレベルのインプレッション、クリック数、コストのみとなり、日単位の粒度まで取得できます。

セラーidおよびキャンペーンidの他に、もう1つディメンションを使用することができます。

ディメンション

  • AdvertiserID
  • CampaignID:必須
  • Seller ID:必須

使用可能なメトリック:

  • 表示数
  • clicks
  • AdvertiserCost

Display:お客様はバナーに複数のセラーを割り当てられるため、Criteoのシステムで最後に商品が表示されたセラーが採用されます。

この記事は役に立ちましたか?
0人中0人がこの記事が役に立ったと言っています
Powered by Zendesk