> 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.md).

# 広告インタラクションイベントのレポート

広告インタラクションイベントレポートは、キャンペーンに追加のレポートレイヤーを提供し、お客様とブランドがカスタマーと広告のインタラクション状況を把握できるようにします。

Shoppable Banner X および Video Banner X 統合では、同じトランスポート、認証、コアフィールドを使用して、同じエンドポイントにイベントを送信します。このセクションを一度お読みいただいてから、有効化したいレポートのガイドに進んでください。

## 統合がどのように連動するか

インタラクションエンドポイントは、3つのレポート成果に対応しています。このページは共通の参照情報であり、各成果には構造情報としてここへリンクする独自のタスクガイドがあります。

```
Ad serving (returns a realised adId)
        │
        ▼
GET /v1/events/ad/interaction   ← this reference: transport, auth, core fields, dedup, errors
        │
        ├─ adInteraction .......... Shoppable Banner reporting
        └─ adInteraction .......... Video reporting
```

| 成果            | エンドポイント        | インタラクションタイプ（概要）                                             |
| ------------- | -------------- | ----------------------------------------------------------- |
| Shoppable バナー | ad/interaction | productImpression、productClick、creativeClick、cart           |
| Video         | ad/interaction | videoクリエイティブView、videoPlay、quartiles、videoComplete、controls |

## 開始前の前提条件（共通の前提条件）

| 前提条件                                                               | 目的                                        |
| ------------------------------------------------------------------ | ----------------------------------------- |
| リテールネームスペース / カタログがプロビジョニングされ、統合ベース URL が発行されていること                 | リテール環境でインタラクションイベントを受信する準備が整っていることを確認します。 |
| 配信された広告が実現された adId                                                 | 各イベントを配信された広告に関連付けることができます。               |
| 広告コンテキスト内でカタログ ID（productCode、catalogId）が利用可能であること。動画の場合は videoId  | 関連するレポートガイドに必要なプロダクトまたは動画のコンテキストを提供します。   |
| 広告セッションごとに一貫したトラッキング ID（sessionId, customerId、または dtmToken）が存在すること | 同じセッション内のイベント間でのアトリビューションと重複排除を有効にします。    |
| アカウントのレポート有効化が確認されていること                                            | 承認されたイベントがレポート出力に正しく連携されることを保証します。        |

### エンドポイントとトランスポート

* メソッド:\*\* HTTPS `GET` クエリパラメーター付き。リクエストボディなし。
* エンドポイント: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* レスポンス: `HTTP 200` 承認時、 `HTTP 400` 検証失敗時、 `5xx` プラットフォームエラー時。

### 認証とセキュリティ

* Fire-and-forget:\*\* イベントがページアンロード後も残るように、 `navigator.sendBeacon`、1×1 画像、または `fetch(…, { keepalive: true })` を使用します。
* **HTTP 400 の再試行はしないでください** — リクエスト形式が正しくないため、再試行しても失敗します。代わりにリクエストを修正してください。
* 特に同意文字列や URL フィールドなど、**すべての値を URL エンコードしてください**。

### コアフィールド（すべてのイベント）

| フィールド                                   | 型      | 必須           | 説明                                                             | 許容値               |
| --------------------------------------- | ------ | ------------ | -------------------------------------------------------------- | ----------------- |
| `adId`                                  | string | はい           | 配信された広告からの実現された広告 ID                                           | —                 |
| `interactionType`                       | string | はい           | イベントタイプ（大文字・小文字を区別する camelCase）                                | 成果ごとのガイドを参照してください |
| `timestamp`                             | string | はい           | イベント日時（ISO 8601。UTC またはリテールローカルを統一して使用）                        | ISO 8601          |
| `sessionId` / `customerId` / `dtmToken` | string | はい（いずれか 1 つ） | トラッキング ID — 少なくとも 1 つが必須。すべて不足している場合、イベントのアトリビューションが行えず、拒否されます | —                 |

広告セッション全体で 1 つのトラッキング ID を再利用し、配信された広告のすべてのイベントで同じ `adId` を再利用します。各 `interactionType` は特定のレポートメトリクスにマッピングされます。各タイプの「レポート目的」については、成果ごとのガイドを参照してください。

### 識別子

イベントを広告、プロダクト、セッションに関連付ける ID です。イベントごとのフィールド要件は各ガイドに記載されています。ここでは、各 ID の取得元についての共通定義を示します。

| 識別子                                     | 概要               | データ元                       | 使用元             |
| --------------------------------------- | ---------------- | -------------------------- | --------------- |
| `adId`                                  | 実現された広告ID        | 配信された広告レスポンス               | すべてのイベント        |
| `productCode` / `catalogId`             | SKUとそのカタログスコープ   | リテールメディアカタログ / 広告コンテキスト    | 商品およびカートのイベント   |
| `videoId`                               | 安定した動画アセットID     | 動画クリエイティブ                  | 動画イベント          |
| `creativeId`                            | 非商品クリエイティブ要素ID   | クリエイティブ                    | `creativeClick` |
| `sessionId` / `customerId` / `dtmToken` | トラッキングID（いずれか1つ） | リテールメディアセッション / ログイン / DTM | すべてのイベント        |

### 実装パターン（ビーコン）

1×1画像を使用し、 `fetch` とともに `keepalive`, or `navigator.sendBeacon` 完全なGET URLを指すようにします。UXのためにレスポンスボディの解析に依存しないでください。同じヘルパーが3つすべての統合に対応します — 成果ごとのガイドは渡す `interactionType` とフィールドのみが異なります。

```javascript
function fireAdInteraction(params) {
  const qs = new URLSearchParams(params);
  const url = `https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?${qs}`;
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url);
  } else {
    new Image().src = url; // fallback
  }
}

// Example: product click (see the Shoppable Banner guide for the full set)
fireAdInteraction({
  adId: "shotgun_0001",
  timestamp: new Date().toISOString(),
  sessionId: getSessionId(),
  productCode: "prod-00001-01",
  catalogId: "catlg-custom-DAA001",
  interactionType: "productClick",
});
```

<br>


---

# 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.md?ask=<question>&goal=<endgoal>
```

`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.