> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/ja/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Banner Xの購入可能バナーインタラクションレポートの連携 Shoppable Bannerは、 Banner X 1つの枠内に複数のコンパニオン商品ホットスポットを持つ広告です。これらのイベントが流れると、キャンペーンレポートはバナーレベルの単一の合計ではなく、インプレッション、クリック、CTR（統合されている場合はカートアクションも含む）といったバナーのパフォーマンスを各コンパニオン商品ごとに分解して表示します。 このガイドでは、Shoppable Bannerのインタラクションタイプのみを扱います。エンドポイント、認証、コアフィールド（`adId`, `timestamp`、トラッキングID）、ビーコンの仕組み、重複排除、テストについては、以下を参照してください [広告インタラクションイベントレポート技術リファレンス](https://help.citrusad.com/retail-media-interface/integration/ja/data-api/api-overview/ad-interaction-events-reporting). ## 前提条件 | 前提条件 | 目的 | | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | 以下をお読みください [技術リファレンス](https://help.citrusad.com/retail-media-interface/integration/ja/data-api/api-overview/ad-interaction-events-reporting) | エンドポイント、認証、コアフィールド、および重複排除要件を確認します。 | | コンパニオン商品が設定されている Banner X クリエイティブ | 商品レベルのインタラクションをクリエイティブに帰属させることができるようにします。 | | 配信された広告が実現された `adId` | 各イベントを配信された広告インスタンスにリンクします。 | | `productCode` および `catalogId` コンパニオン商品ごとに利用可能 | レポートで使用される商品およびカタログを特定します。 | | 商品タイルで合意された視認性ルール | 商品タイルが閲覧されたとみなされるタイミングを次のように定義します `productImpression`. | | 広告セッションごとの一貫したトラッキングID | 以下を使用したアトリビューションと重複排除をサポートします `sessionId`, `customerId`, or `dtmToken`. | ## Shoppable Banner Reportingのインタラクションタイプ これらは `adInteraction` イベント（非 `moduleId`）。コアフィールドに加えて以下のキーフィールドを送信してください。 `productImpression` および `productClick` は Products タブを有効化する2つのイベントです。両方を呼び出してください。 | `interactionType` | キーフィールド | 呼び出しのタイミング | レポート作成の目的 | | ------------------- | ----------------------------------------------------------- | ------------------------------ | -------------------------------------------- | | `productImpression` | `productCode`, `catalogId` | 視認性ルールに従って商品タイル/SKUが表示可能になったとき | 商品ごとのインプレッション — インプレッション列（およびゼロクリックの行）を満たします | | `productClick` | `productCode`, `catalogId` | ショッパーが商品タイル/SKUをクリックする | 商品ごとのクリック — クリック数とCTRを促進 | | `creativeClick` | `creativeId` | 非商品クリエイティブ要素のクリック | 非商品クリエイティブへのエンゲージメント | | `cart` | `productCode`, `catalogId`, `units`、オプション `conversionValue` | 広告コンテキストからのカート変更 | カート追加の意図 / 商品価値 | ## 次に関する視認性ルール： `productImpression` | ルール | ガイダンス | | ------------------------- | ----------------------------------------------- | | タイルが閲覧されたとみなされるタイミングを定義する | 表示割合や画面上の表示時間などの視認性ルールに合意し、Webとアプリ全体で一貫して適用します。 | | 視認性の発生ごとに1回インプレッションを発火させる | スクロールのブレや再描画をデバウンスし、1回の表示が何度もカウントされないようにします。 | ## カート：現在の絶対数量を送信する 発火 `cart` カート操作（最初の追加、各変更 `+`、各変更 `−`、削除（ `0`まで））のたびに送信され、 `units` にはデルタ値ではなく、現在の絶対的な数量を設定します。現在の合計を再送信することで、重複排除下でもカウントが正確に保たれます。利用可能な場合は `conversionValue` を追加してください。 {% hint style="info" %} **例** — 買い物客が商品を追加し、2回増やしてから削除する場合:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## ステップごとの実装 ### ステップ 1 — 広告コンテキストの取得 配信された広告から実効 `adId` を読み取り、各コンパニオンタイルの `productCode`/`catalogId` を取得します。セッション用に1つのトラッキングIDを定義し、インプレッションとクリックで再利用します。 ### ステップ 2 — 商品インプレッションの発生 タイルが視認性ルールを満たしたら、その商品に対して `productImpression` を1回発生させます。 ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### ステップ 3 — 商品クリックの発生 ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productClick", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### ステップ 4 — カート変更の発生 追加/更新時に、 `cart` 絶対的な現在の値 `units` その製品について（および `conversionValue` それがある場合は）— 上記のカートルールを参照してください。 ## リクエストの例 完全な GET URL（可読性のために改行されています — 単一のエンコードされたクエリ文字列として送信してください）。 ### 商品インプレッション ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:00Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productImpression ``` ### 商品クリック ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:30Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productClick ``` ### 広告からのカート追加 ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:16:00Z &customerId=cust-abc-123 &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=cart &units=2 &conversionValue=29.99 ``` ## 理想的な状態 | 確認項目 | 詳細 | | --------------------- | ----------------------------------------------------------------------------- | | イベントは HTTP 200 を返します | `productImpression` および `productClick` PRE/QA 環境で HTTP 200 を返します。 | | 「商品」タブにすべてのデータが入っています | 設定されたすべてのコンパニオン製品が表示されます。エンゲージメントがゼロの行も含まれます（インプレッションによって、クリックゼロの行にデータが入ります）。 | | 重複排除が機能しています | 同じインプレッション/クリックを再度発生させても、カウントは一定を保ちます。 | ## トラブルシューティング（ショッパブルバナー固有） | 現象 | 修正方法 | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 必須の商品イベントが届かない | バナーが Banner X クリエイティブ段階でコンパニオン製品に関連付けられていること、および `productImpression` および `productClick` が発火していることを確認します `productCode`/`catalogId`. | | スクロールや再レンダリングごとにインプレッションが発火する | 視認可能発生ごとに製品 1 つにつき 1 つの `productImpression` を発火させ、デバウンス処理を行います。 | | 「商品」タブに誤った製品が表示される、または製品が表示されない | カタログとの `productCode`/`catalogId` 不一致の可能性があります — 送信する ID とカタログフィードを照合してください。 | | カートの数が正しくなさそうに見える | 差分を送信しています — 絶対的な現在の値を送信してください `units`. | 一般的なエンドポイントのトラブルシューティングについては、 [広告インタラクションイベントレポート技術リファレンス](https://help.citrusad.com/retail-media-interface/integration/ja/data-api/api-overview/ad-interaction-events-reporting) トラブルシューティングセクションを参照してください。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/integration/ja/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-reporting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.