> 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-video-interaction-reporting.md).

# Banner Xの動画インタラクションレポートの連携

## これにより有効化される機能

動画レポートでは、買い物客の視聴状況（クリエイティブの表示、再生、四分位数ごとの進捗状況、完了）に加えて、操作アクション（スキップ、一時停止、消音）が表示されます。これは以下に対応しています： Banner X 動画クリエイティブ。

Banner X 動画は通常、統合済みのVAST 4.0プレイヤーを介してレンダリングされるため、このレポート機能を有効にする最も簡単な方法は、プレイヤーにイベントを発火させることです： Epsilon 広告レスポンスの `adm` フィールドでVASTタグを返し、各再生マイルストーンをインタラクションエンドポイントに向ける `<TrackingEvents>` ブロックを注入します。このガイドでは、そのブロックの作成方法について説明します。プレイヤーがVASTトラッキングを出力できない場合（または動画がVAST経由で配信されない場合）は、代わりに [手動ビーコンフォールバック](#alternative--fire-beacons-from-player-callbacks) を使用してください。

このガイドでは、動画インタラクションのタイプと、それらをVAST経由で接続する方法のみを扱います。エンドポイント、認証、コアフィールド、ビーコンの仕組み、重複排除、およびテストについては、[**技術リファレンス**](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference).

## 前提条件

| 前提条件                                                                                                          | これが重要である理由                                                                          |
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 以下を読む： [技術リファレンス](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) | すべての動画イベントで使用されるエンドポイント、認証、コアフィールド、および重複排除ルールをカバーしています。                             |
| 配信された広告は以下を返します： `adId` (`citrusAdId`)                                                                        | すべての動画インタラクションが配信された広告に帰属可能であることを保証します。                                             |
| 以下をレンダリングするVAST 4.0対応プレイヤー： `adm` タグおよび発火 `<TrackingEvents>`                                                  | プレイヤーは、実際の再生進捗に合わせて挿入されたビーコンを発火させます。                                                |
| プレイヤーはVASTマクロを展開します（例： `[TIMESTAMP]`, `[CACHEBUSTING]`)                                                       | 推測する代わりに、プレイヤーが発火時に各ビーコンにタイムスタンプを付与できるようにします。                                       |
| 以下を読み取ります： `UniversalAdId` `idValue` 以下から： `<Creative>`                                                       | これは動画ごとの安定したIDです Epsilon 以下として使用： `videoId` ファネルを統合するため（1つの広告に複数の動画を含めることができます）。    |
| 広告セッションごとの一貫したトラッキングID                                                                                        | 使用する `sessionId`, `customerId`, or `dtmToken` レポートがセッション全体でイベントを結合できるように、一貫して使用します。 |

## 内容 Epsilon 今日配信されるもの（および追加するもの）

この `adm` オブジェクト（ Banner X レスポンス内の）はVAST 4.0タグです。 Epsilon は、すでに**インプレッション**と**クリック**のトラッキングを組み込んでいます（`<Impression>` および `<VideoClicks><ClickTracking>`）。進捗状況やインタラクションのトラッキングは配信**しません**。これは、お客様が挿入するものです。

インタラクションエンドポイントは、以下のすべての動画タイプをすでにサポートしています。URLsが `<TrackingEvents>` ビーコンである `GET /v1/events/ad/interaction` ブロックを追加することで、2つをブリッジします。プレーヤーが各マイルストーンを通過すると、対応するURLが送信されます。 Epsilonから配信される `<Impression>` および `<ClickTracking>` ノードはそのままにしておきます。お客様は**追加**するだけです `<TrackingEvents>`.

## 動画レポート用インタラクションタイプ

すべての動画イベントでコアフィールドに加え、 `videoId` を送信します。 `iabConsentString` はすべてのタイプでオプションのフィールドです（URLエンコード済み）。プレーヤーが各マイルストーンに到達したときに、同じ `adId`, `videoId`およびトラッキングIDを視聴セッション全体で再利用して、ファネルイベントを順番に送信します。

### ファネルイベント

| `interactionType`    | 送信するタイミング                   | レポートの目的                     |
| -------------------- | --------------------------- | --------------------------- |
| `videoCreativeView`  | 最初の動画フレームがレンダリングされたとき       | 動画インプレッションの基準               |
| `videoPlay`          | 再生開始（ポリシーに従ったユーザー主導または自動再生） | 動画開始率                       |
| `videoFirstQuartile` | 再生時間の25%を視聴                 | 動画ファネル Q1                   |
| `videoMidpoint`      | 50%を視聴                      | 動画ファネル Q2                   |
| `videoThirdQuartile` | 75%を視聴                      | 動画ファネル Q3                   |
| `videoComplete`      | 100%を視聴                     | 完了率 — クリエイティブの有効性と動画広告費の妥当性 |

### コントロールイベント

| `interactionType` | 送信するタイミング       | レポートの目的                   |
| ----------------- | --------------- | ------------------------- |
| `videoSkip`       | 完了前にユーザーがスキップ   | スキップ率 — 途中離脱 / クリエイティブの問題 |
| `videoPause`      | ユーザーが一時停止       | エンゲージメントの深さ / 気の散り        |
| `videoResume`     | 一時停止後にユーザーが再生再開 | 一時停止後の再エンゲージメント           |
| `videoMute`       | ユーザーが音声ミュート     | 音声エンゲージメントの好み             |
| `videoUnmute`     | ユーザーがミュート解除     | アクティブな音声への関心              |

## VAST イベントの対応付け先: Epsilon インタラクションタイプ

VAST プレイヤーは標準の `<Tracking event="…">` コールバックを発生させます。以下の行ごとに 1 つの `<Tracking>` ノードを注入し、対応付けられたインタラクション エンドポイントを指すようにします `interactionType`.

| VAST `<Tracking event>` | Epsilon `interactionType` |
| ----------------------- | ------------------------- |
| `creativeView`          | `videoCreativeView`       |
| `start`                 | `videoPlay`               |
| `firstQuartile`         | `videoFirstQuartile`      |
| `midpoint`              | `videoMidpoint`           |
| `thirdQuartile`         | `videoThirdQuartile`      |
| `complete`              | `videoComplete`           |
| `skip`                  | `videoSkip`               |
| `pause`                 | `videoPause`              |
| `resume`                | `videoResume`             |
| `mute`                  | `videoMute`               |
| `unmute`                | `videoUnmute`             |

上記に記載のないその他の VAST イベント（例： `progress`, `fullscreen`, `exitFullscreen`, `rewind`, `close`）は以下の対象外です： Epsilon 動画レポート — これらに対してビーコンを挿入しないでください。

## トラッキング URL の作成

挿入される各 `<Tracking>` URL は、単一の URL エンコードされた `GET` ビーコンです。ビルド時に広告レスポンスの値から作成し、タイムスタンプには VAST マクロを使用して、プレイヤーが実行時にタイムスタンプを付与するようにします。

```
https://integration.{url}.citrusad.com/v1/events/ad/interaction
  ?adId={citrusAdId}
  &interactionType={mapped type, e.g. videoFirstQuartile}
  &videoId={UniversalAdId idValue for this creative}
  &sessionId={your session tracking id}
  &timestamp=[TIMESTAMP]
```

* `adId` — 参照 `citrusAdId` 配信されたバナーから。
* `videoId` — 参照 `idValue` 以下の `<UniversalAdId>` 配線しているクリエイティブの。これはクリエイティブ単位です：広告に複数の動画が含まれている場合、各 `<Creative>` は独自の `<TrackingEvents>` ブロック（**その**クリエイティブの `idValue`を使用）を取得するため、ファネルは実際に視聴された動画に関連付けられます。
* `sessionId` — あなたの `sessionId` (or `customerId` / `dtmToken`）をビルド時に注入します。エンドポイントはトラッキングIDのないイベントを拒否します。
* `timestamp` — 次のを使用してください： `[TIMESTAMP]` VASTマクロを使用して、プレイヤーが実際のISO 8601発火時刻に置換できるようにします。お使いのプレイヤーがこれをサポートしていない場合は、別の方法でビーコンにタイムスタンプを付与してください。ただし、すべてのイベントに対して単一の時間をハードコードしないでください。
* 追加 `[CACHEBUSTING]` プレイヤーが同一のURLをキャッシュする場合は、使い捨てパラメータとして追加してください。

## 挿入 `<TrackingEvents>` 配信されたVASTタグ内へ

次を追加： `<TrackingEvents>` ブロック（各 `<Creative>`'s `<Linear>` 要素の内部、 `<VideoClicks>`の後。VAST 4.0のサンプルと一致させます）。以下では、 `<Impression>` および `<ClickTracking>` は Epsilonによって配信され、手付かずのまま残されます。ハイライト表示された `<TrackingEvents>` ブロックが追加する内容です。注： `videoId` はこのクリエイティブの `idValue` (`…000003`).

```xml
<Creative>
  <UniversalAdId idRegistry="citrusad.com" idValue="00000000-0000-0000-0000-000000000003">
    00000000-0000-0000-0000-000000000003
  </UniversalAdId>
  <Linear>
    <Duration>00:00:15</Duration>
    <MediaFiles>
      <MediaFile delivery="progressive" type="video/mp4" width="1920" height="1080">
        <![CDATA[https://example.com/media/example-video-2.mp4]]>
      </MediaFile>
    </MediaFiles>
    <VideoClicks>
      <ClickTracking>
        <![CDATA[https://integration.{retailer}.citrusad.com/v1/resource/second-c/example_ad_id]]>
      </ClickTracking>
      <ClickThrough></ClickThrough>
    </VideoClicks>

    <!-- Injected by the retailer: maps VAST playback events to the Epsilon interaction endpoint -->
    <TrackingEvents>
      <Tracking event="creativeView"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoCreativeView&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="start"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoPlay&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="firstQuartile"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoFirstQuartile&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="midpoint"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoMidpoint&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="thirdQuartile"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoThirdQuartile&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="complete"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoComplete&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="skip"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoSkip&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="pause"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoPause&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="resume"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoResume&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="mute"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoMute&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
      <Tracking event="unmute"><![CDATA[https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?adId=example_ad_id&interactionType=videoUnmute&videoId=00000000-0000-0000-0000-000000000003&sessionId=sess_001&timestamp=[TIMESTAMP]]]></Tracking>
    </TrackingEvents>
  </Linear>
</Creative>
```

{% hint style="info" %}
**1つの広告に複数の動画** 各 `<TrackingEvents>` ごとに `<Creative>`ブロックを繰り返します。それぞれ独自の `UniversalAdId` `idValue` as `videoId`を使用します。**1つの `idValue`** を複数のクリエイティブ間で決して共有しないでください。これにより\*\* Epsilon がファネルを配信された特定の動画に属性付けできるようになります。\*\*
{% endhint %}

## 再生シーケンス

ファネルイベントは、フル視聴において次の順序に従います：

`videoCreativeView` → `videoPlay` → `videoFirstQuartile` → `videoMidpoint` → `videoThirdQuartile` → `videoComplete`

| ルール             | ガイダンス                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------- |
| ファネルのマイルストーン    | 実際の再生の進行状況に関連付ける必要があります。VASTプレイヤーは実際の進行状況に応じてクォータイルを発火させます。シーク時にこれらを合成しないでください。                |
| 制御イベント          | `videoSkip`, `videoPause`, `videoResume`, `videoMute`、および `videoUnmute` 再生中の任意の時点で発火する場合があります。 |
| セッションのアトリビューション | セッション全体で同じ `adId`, `videoId` (`idValue`）、およびトラッキングIDを再利用して、ファネルが結びつくようにします。                    |

## 代替案 — プレイヤーのコールバックからビーコンを発生させる

プレイヤーがVASTを送信できない場合 `<TrackingEvents>`、または動画がVAST経由で配信されない場合は、プレイヤーのコールバックから直接同じビーコンを発生させます。エンドポイントとフィールドは同一です。VASTタグの代わりにコード内でURLを組み立てる点が異なります。

### ステップ 1 — コンテキストのキャプチャ

読み取り `adId` (`citrusAdId`）とクリエイティブの `UniversalAdId` `idValue` として使用する `videoId`。セッショントラッキング ID を再利用します。

### ステップ 2 — プレイヤーのコールバックからファンネルのマイルストーンを発火する

```javascript
function fireVideo(interactionType) {
  navigator.sendBeacon(
    "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" +
    new URLSearchParams({
      adId, interactionType, videoId, sessionId,
      timestamp: new Date().toISOString()
    })
  );
}
// e.g. player.on("firstquartile", () => fireVideo("videoFirstQuartile"));
```

### ステップ 3 — 制御イベントが発生したら発火する

スキップ/一時停止/再開/ミュート/ミュート解除をフックし、一致するタイプを発火させます。急速な切り替えはデバウンスします。

## リクエストのサンプル

注入された VAST URL と手動ビーコンは同じに解決されます `GET` リクエスト。以下の完全な URL は読みやすさのために改行されています — 単一のエンコードされたクエリ文字列として送信してください。

### 動画の再生

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=banner_vid001
  &timestamp=2026-05-20T10:20:00Z
  &sessionId=sess_001
  &interactionType=videoPlay
  &videoId=00000000-0000-0000-0000-000000000003
```

### 四分位数のマイルストーン

次と同じ形状 `videoFirstQuartile` / `videoMidpoint` / `videoThirdQuartile` / `videoComplete`.

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=banner_vid001
  &timestamp=2026-05-20T10:20:15Z
  &sessionId=sess_001
  &interactionType=videoFirstQuartile
  &videoId=00000000-0000-0000-0000-000000000003
```

### 制御イベント

次と同じ形状 `videoSkip` / `videoPause` / `videoResume` / `videoMute` / `videoUnmute`.

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=banner_vid001
  &timestamp=2026-05-20T10:20:40Z
  &sessionId=sess_001
  &interactionType=videoSkip
  &videoId=00000000-0000-0000-0000-000000000003
```

## 良好な状態の例

| エリア         | 期待される結果                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| 挿入されたトラッキング | 各 `<Creative>` には1つの `<TrackingEvents>` ブロックが含まれます。すべての `<Tracking>` URLはそのクリエイティブの `idValue` as `videoId`. |
| 四分位数イベント    | 四分位数は順序通りに届き、フル再生には正確に1つの `videoComplete` が含まれます。                                                           |
| 制御イベント      | イベントは重複排除ルールを超えて重複することはありません。                                                                               |
| 再視聴         | 同じセッション内での再視聴は再利用され `videoId` アトリビューション可能なままとなります。                                                          |

## トラブルシューティング（動画固有）

| 問題                                | 考えられる原因                                               | 対処法                                                                                                     |
| --------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 進行状況イベントが届かず、インプレッション/クリックのみが発生する | `<TrackingEvents>` が注入されていないか、外部に追加されています `<Linear>`. | 各内部にブロックを追加し `<Creative>`'s `<Linear>` プレーヤーがそれを解析することを確認します。                                           |
| すべてのイベントが1つのタイムスタンプを共有している        | `[TIMESTAMP]` マクロがプレーヤーによって展開されていません。                 | マクロのサポートを確認するか、発火ごとにタイムスタンプを付与します。1つの時間をハードコードしないでください。                                                 |
| イベントは到達するが、動画にアトリビューションできない       | `videoId` クリエイティブ間で欠落しているか、再利用されています。                 | 設定してください `videoId` を各クリエイティブ固有の `UniversalAdId` `idValue`.                                              |
| イベントが HTTP 400 を返す                | 未エンコードの URL、トラッキング ID の欠落、または不明な `interactionType`.   | 全体を URL エンコードします `<Tracking>` URL。以下を含めてください： `sessionId`/`customerId`/`dtmToken`マップされた正確なタイプを使用してください。 |
| イベントが再生に一致せず固定間隔で表示される            | 実際の進行状況ではなくタイマーでビーコンが発火しています。                         | 各イベントをプレーヤーの実際の進行状況コールバックにバインドします（VASTがこれを行います）。                                                        |
| `videoComplete` が複数回発火する          | 完了ハンドラーがループ時や再生時にも発火しています。                            | デバウンスし、1回の再生につき単一の完了に制限します。                                                                             |
| `videoComplete` が読み込み時に発火する       | 完了イベントが100%の再生ではなく読み込みに紐付いています。                       | 紐付けてください `videoComplete` を真の再生終了に。                                                                      |

一般的なエンドポイントのトラブルシューティングについては、以下を参照してください： [技術リファレンス](https://developers.citrusad.com/integration/docs/ad-interaction-events-technical-reference) トラブルシューティングセクション。

<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/integrate-banner-x-video-interaction-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.