> 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/ko/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` 전체 퍼널을 연결하기 위해(단일 광고에 둘 이상의 동영상이 포함될 수 있음). |
| 광고 세션당 일관된 추적 ID                                                                                                  | 사용 `sessionId`, `customerId`, or `dtmToken` 세션 전체에서 이벤트를 결합하여 리포팅할 수 있도록 일관되게 적용됩니다.            |

## 무엇이 Epsilon 오늘 제공되는 항목(및 추가하는 항목)

해당 `adm` 의 객체 Banner X 응답은 VAST 4.0 태그입니다. Epsilon 이미 **노출** 및 **클릭** 추적을 연결해 두었습니다 (`<Impression>` 및 `<VideoClicks><ClickTracking>`). 진행 상황 및 상호작용 추적은 제공하지 **않습니다** — 이는 귀하가 주입하는 부분입니다.

상호작용 엔드포인트는 이미 아래의 모든 비디오 유형을 수용합니다. 귀하는 URLs가 `<TrackingEvents>` 블록인 `GET /v1/events/ad/interaction` 비콘으로 두 항목을 연결합니다. 플레이어가 각 마일스톤을 지날 때 일치하는 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="…">` 콜백을 실행합니다. 매핑된 `<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" %}
**한 광고에 여러 동영상 포함** 모든 `<TrackingEvents>` 에 대해 `<Creative>`블록을 반복하고, 각각 고유한 `UniversalAdId` `idValue` as `videoId`을(를) 사용합니다. \*\*절대로 하나의 `idValue`을(를) **여러 크리에이티브 간에 공유하지 마십시오. 이것이 바로 Epsilon 에서 퍼널을 제공된 특정 동영상에 귀속시킬 수 있는 이유입니다.**
{% endhint %}

## 재생 순서

퍼널 이벤트는 전체 조회 기간 동안 다음 순서를 따릅니다.

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

| 규칙      | 지침                                                                                                    |
| ------- | ----------------------------------------------------------------------------------------------------- |
| 퍼널 마일스톤 | 실제 재생 진행 상황과 연결되어야 합니다. VAST 플레이어는 실제 진행 시 사분위수를 발화합니다. 탐색(seek) 시 이를 인위적으로 합성하지 마십시오.                |
| 제어 이벤트  | `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>` 하나를 가짐 `<TrackingEvents>` 블록; 모든 `<Tracking>` URL은 해당 크리에이티브의 `idValue` as `videoId`. |
| 사분위수 이벤트 | 사분위수는 순서대로 도달하며, 정확히 하나의 `videoComplete` 전체 시청을 위한 것입니다.                                               |
| 제어 이벤트   | 중복 제거 규칙을 넘어서는 이벤트는 중복되지 않습니다.                                                                         |
| 재시청      | 동일한 세션 내의 재시청은 다음을 재사용합니다. `videoId` 귀속 가능한 상태로 유지됩니다.                                                 |

## 문제 해결(비디오 전용)

| 문제                              | 추정 원인                                                | 조치                                                                                          |
| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 진행 이벤트가 수신되지 않고 임프레션/클릭만 수신됨    | `<TrackingEvents>` 주입되지 않았거나 외부에 추가됨 `<Linear>`.     | 각 내부에 블록을 추가하세요 `<Creative>`'s `<Linear>` 그리고 플레이어가 이를 파싱하는지 확인하세요.                         |
| 모든 이벤트가 하나의 타임스탬프를 공유함          | `[TIMESTAMP]` 매크로가 플레이어에 의해 확장되지 않았습니다.              | 매크로 지원을 확인하거나 실행 시마다 스탬프를 찍으세요. 시간을 하드코딩하지 마세요.                                             |
| 이벤트가 도달하지만 비디오에 귀속될 수 없음        | `videoId` 누락되었거나 크리에이티브 전체에서 재사용되었습니다.               | 설정 `videoId` 각 크리에이티브의 고유한 `UniversalAdId` `idValue`.                                       |
| 이벤트가 HTTP 400을 반환함              | 인코딩되지 않은 URL, 누락된 추적 ID 또는 알 수 없음 `interactionType`. | 전체를 URL 인코딩하세요 `<Tracking>` URL; 포함 `sessionId`/`customerId`/`dtmToken`; 정확히 매핑된 유형을 사용하세요. |
| 이벤트가 재생과 일치하지 않고 고정된 간격으로 나타남   | 실제 진행 상황 대신 타이머에 의해 비콘이 실행되었습니다.                     | 각 이벤트를 플레이어의 실제 진행 콜백에 바인딩하세요(VAST가 자동으로 처리함).                                              |
| `videoComplete` 이(가) 두 번 이상 실행됨 | 완료 핸들러가 루프 또는 재생 시에도 실행됩니다.                          | 재생당 단일 완료로 디바운스 및 게이트 처리하세요.                                                                |
| `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/ko/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.