パートナーAPI

広告キャッシング

広告生成エンドポイントから返される広告は、広告の種類にかかわらず、絶対に必要な場合を除き、キャッシュされるべきではありません。小売業者のウェブサイトでページが読み込まれるたびに、新しい広告生成リクエストが適切なデータでCitrusAdに送信され、新たな広告セットが生成されるはずです。

小売業者がこれに対応できない場合、CitrusAdがキャッシュ機能を提供し、小売業者が複数の顧客に広告を繰り返し提供できるようにします。

🚧

CitrusAdの有効なクリックの基準を満たすインプレッションとクリックは、それに応じて課金されます。このため、CitrusAdでは、キャッシュのタイムフレームを分単位で最小化し、過剰に支出する可能性を減らすことを強く推奨しています。

統合の要件

sessionId は、広告を複数のセッションに配信できるため、広告リクエストでは不要になりました。

広告のキャッシュを希望する小売業者は、次の要件を満たす必要があります。

  • CitrusAdへの広告リクエストで、オプション欄に “cached”: true の新しいパラメータを送信すること。
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
                         "filterMode": "AndOr",
                         "cached": true
                             },
    "maxNumberOfAds": 3    
}
  • 注文をレポートする際に、 sessionId のアトリビューションメソッドと統合すること。
  • インプレッションとクリックのレポートにエンコードされた sessionId を送信すること。
  • インプレッションとクリックに関するレポートで、イベントのタイムスタンプを送信すること。イベント間のタイムゾーンは一定であるべきですが、どのタイムゾーンを使用するかは小売業者が決定できます。フォーマットはISO-8601形式になります。
https://integration.<ENV>.citrusad.com/v1/resource/second-c/<AD_ID>?sessionId=<SESSION_ID>&event_ts=20220127152500

これが運用段階に入ると、CitrusAd側で関連処理が発生します。CitrusAdによる追加の設定は必要ありません。

キャッシュの仕組み

キャッシュされた広告には、「window」という設定可能なプロパティがあります。このウィンドウはすべての広告タイプに適用されます。また、CitrusAdからの応答ですでに渡されている「expiry」プロパティがあります。
これらのプロパティで、インプレッションとクリックの処理方法を決定します。場合によっては、CitrusAdにて新しいAdIdを作成し、それに従ってインプレッション/クリックを処理します。このようにして、CitrusAdは複数の顧客セッションでアトリビューションが完全に機能するようにします。

シナリオ1

「ウィンドウ」内の同じsessionIdの広告については、同じadIdとして扱われます。

2640

シナリオ2

異なるsessionIdを持つ広告については、新しいAdIdが作成され、新しいインプレッションまたはクリックとして処理されます。

2606

シナリオ3

広告の有効期限外でもインプレッションやクリックはすべて記録されますが、課金やレポートは行われません。

2612

シナリオ4

インプレッションがレポートされていないウィンドウで発生したクリックは、CitrusAdにてクリックと推定されます。これは、現在のシステム全体の動作です。

この動作は、ウィンドウを大きくし、小売業者がキャッシュを減らすことで軽減することができます。

2650

複数の顧客に広告を配信する場合、それぞれのシナリオは実際には単独で発生することが予想されます。

2670

🚧

支出超過のリスク

この機能により、小売業者はCitrusAdに広告を依頼することなく、複数の顧客に対して複数回、広告を配信することができるようになります。

この機能には、キャンペーンやウォレットの変更方法に対する変更は実装されていません。広告がキャッシュされるほど、資金がなくなっているキャンペーンやウォレットの広告が配信される可能性が高くなります。

CitrusAdは、資金がある際に配信された広告について、現在資金が不足しているキャンペーンやウォレットのインプレッション/クリックを処理し、課金します。

このような場合に、過剰な支出を抑える方法は3つあります。

  • キャッシュを最小限のタイムフレームに削減する（推奨）
    広告の配信が長くなるほど、資金がなくなったキャンペーン/ウォレットの広告が配信されるリスクが高くなります。

  • CitrusAdにてすべての広告の「有効期限」を短縮
    CitrusAdは、配信後に広告が「有効」とみなされるタイムフレームを短縮することができます。この有効期限後のインプレッション/クリックは無効になります。

  • CitrusAdにてすべての広告の「ウィンドウ」を拡大
    ウィンドウが大きくなるほど、新しいインプレッション/クリックの量が減ります。ただし、これによりレポートされるインプレッション/クリックが減ります。