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

# 광고 상호작용 이벤트 보고

광고 상호작용 이벤트 리포팅은 귀사와 귀사의 브랜드가 고객이 광고와 어떻게 상호작용하는지 이해할 수 있도록 캠페인에 추가적인 리포팅 계층을 제공합니다.

Shoppable Banner X 및 비디오 Banner X 통합은 동일한 전송 방식, 인증 및 핵심 필드를 사용하여 동일한 엔드포인트로 이벤트를 전송합니다. 이 내용을 한 번 읽은 후 활성화하려는 보고서의 가이드를 따르세요.

## 통합 작동 방식

상호작용 엔드포인트는 세 가지 리포팅 결과를 지원합니다. 이 페이지는 공유 참조 문서이며, 각 결과에는 여기에 연동되는 자체 작업 가이드가 있습니다.

```
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           |
| 비디오          | 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 | 예 (하나 이상) | 추적 ID — 최소 하나 필수, 모두 누락된 경우 이벤트를 기여로 산정할 수 없으며 거부됨 | —              |

전체 광고 세션에 대해 하나의 추적 ID를 재사용하고, 해당 게재 광고의 모든 이벤트에 동일한 `adId` 를 재사용하세요. 각 `interactionType` 는 특정 리포팅 지표에 매핑됩니다. 각 유형의 "리포팅 목적"은 결과별 가이드를 참조하세요.

### 식별자

이벤트를 광고, 상품 및 세션에 연결하는 ID입니다. 이벤트별 필드 요구사항은 각 가이드에 있으며, 이는 각 ID의 출처에 대한 공유 정의입니다.

| 식별자                                     | 개요               | 출처                  | 사용처             |
| --------------------------------------- | ---------------- | ------------------- | --------------- |
| `adId`                                  | 실현된 광고 ID        | 제공된 광고 응답           | 모든 이벤트          |
| `productCode` / `catalogId`             | SKU + 해당 카탈로그 범위 | 리테일러 카탈로그 / 광고 컨텍스트 | 상품 및 장바구니 이벤트   |
| `videoId`                               | 안정적인 비디오 자산 ID   | 비디오 크리에이티브          | 비디오 이벤트         |
| `creativeId`                            | 비상품 크리에이티브 요소 ID | 크리에이티브              | `creativeClick` |
| `sessionId` / `customerId` / `dtmToken` | 추적 ID (아무거나 하나)  | 리테일러 세션 / 로그인 / DTM | 모든 이벤트          |

### 구현 패턴 (비콘)

1×1 이미지를 사용하고, `fetch` 다음과 함께 `keepalive`, or `navigator.sendBeacon` 전체 GET URL을 가리키도록 합니다. UX 처리를 위해 응답 본문을 구문 분석하는 데 의존하지 마세요. 동일한 헬퍼가 세 가지 연동을 모두 지원하며, 결과별 가이드는 전달하는 `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/ko/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.