> 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-shoppable-banner-interaction-reporting.md). # Banner X 쇼퍼블 배너 상호작용 보고 연동 쇼퍼블 배너는 하나의 지면에 여러 개의 연관 상품 핫스팟이 포함된 Banner X 광고입니다. 이러한 이벤트가 수집되면 캠페인 보고서는 단일 배너 수준의 합계 대신 각 연관 상품별로 배너 성과(노출수, 클릭수, CTR 및 연동된 경우 장바구니 담기 작업)를 세분화하여 제공합니다. 이 가이드는 쇼퍼블 배너 상호작용 유형만 다룹니다. 엔드포인트, 인증, 핵심 필드(`adId`, `timestamp`, 추적 ID), 비콘 메커니즘, 중복 제거 및 테스트에 대한 내용은 다음을 참조하세요. [광고 상호작용 이벤트 리포팅 기술 참조](https://help.citrusad.com/retail-media-interface/integration/ko/data-api/api-overview/ad-interaction-events-reporting). ## 사전 요구 사항 | 사전 요구 사항 | 목적 | | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | 다음을 읽어보세요. [기술 참조](https://help.citrusad.com/retail-media-interface/integration/ko/data-api/api-overview/ad-interaction-events-reporting) | 엔드포인트, 인증, 핵심 필드 및 중복 제거 요구 사항을 확인합니다. | | 다음에 구성된 연관 상품 Banner X 크리에이티브 | 상품 수준의 상호작용을 크리에이티브에 기여할 수 있도록 합니다. | | 게재된 광고가 실현된 결과를 반환합니다. `adId` | 각 이벤트를 전달된 광고 인스턴스에 연결합니다. | | `productCode` 및 `catalogId` 연관 상품별로 사용 가능 | 리포팅에 사용되는 상품 및 카탈로그를 식별합니다. | | 상품 타일에 대해 합의된 조회 가능성 규칙 | 상품 타일이 언제 노출된 것으로 간주되는지 정의합니다. `productImpression`. | | 광고 세션당 일관된 추적 ID | 다음을 사용한 기여 및 중복 제거를 지원합니다. `sessionId`, `customerId`, or `dtmToken`. | ## 쇼퍼블 배너 리포팅을 위한 상호작용 유형 다음은 `adInteraction` 이벤트입니다( `moduleId`없음). 아래의 키 필드와 핵심 필드를 함께 전송하세요. `productImpression` 및 `productClick` 은 상품 탭을 활성화하는 두 가지 이벤트입니다. 두 이벤트를 모두 실행하세요. | `interactionType` | 키 필드 | 실행 시점 | 리포팅 목적 | | ------------------- | ------------------------------------------------------------ | ---------------------------------- | ------------------------------ | | `productImpression` | `productCode`, `catalogId` | 귀하의 조회 가능성 규칙에 따라 제품 타일/SKU가 표시될 때 | 제품별 노출수 — 노출수 열(및 제로 클릭 행)을 채움 | | `productClick` | `productCode`, `catalogId` | 쇼퍼가 제품 타일/SKU를 클릭할 때 | 제품별 클릭수 — 클릭수 및 CTR을 유도함 | | `creativeClick` | `creativeId` | 제품이 아닌 크리에이티브 요소를 클릭할 때 | 제품이 아닌 크리에이티브와의 참여 | | `cart` | `productCode`, `catalogId`, `units`, 선택 사항 `conversionValue` | 광고 컨텍스트에서의 장바구니 변경 | 장바구니 담기 의도 / 제품 가치 | ## 다음 항목에 대한 조회 가능성 규칙: `productImpression` | 규칙 | 지침 | | ----------------------------- | ---------------------------------------------------------- | | 타일이 조회된 것으로 간주되는 시점을 정의합니다. | 화면에 표시된 시간과 표시된 비율 등의 조회 가능성 규칙에 합의하고 웹과 앱 전체에 일관되게 적용합니다. | | 조회 가능성 발생 시마다 노출을 한 번 발생시킵니다. | 스크롤 떨림 및 다시 렌더링을 디바운스하여 단일 조회가 여러 번 집계되지 않도록 합니다. | ## 장바구니: 절대 현재 수량 전송 모든 장바구니 상호작용(최초 추가, 각 `cart` 마다, 각 `+`마다, 및 제거( `−`로 돌아감) 시마다 `0`를 증감값이 아닌 절대 현재 수량으로 설정하여 `units` 를 실행합니다. 현재 총계를 다시 전송하면 중복 제거 하에서도 집계가 정확하게 유지됩니다. 확보한 경우 `conversionValue` 를 추가하세요. {% hint style="info" %} **예시** — 쇼퍼가 제품을 추가하고, 두 번 증량한 후, 제거하는 경우:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## 단계별 구현 ### 단계 1 — 광고 컨텍스트 캡처 게재된 광고에서 실현된 `adId` 를 읽고, 각 동반 타일에 대해 `productCode`/`catalogId` 를 읽습니다. 세션에 대한 하나의 추적 ID를 설정하고 노출 및 클릭에 재사용합니다. ### 단계 2 — 제품 노출 발생 타일이 조회 가능성 규칙을 충족하면 해당 제품에 대해 `productImpression` 를 한 번 발생시킵니다. ```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을 반환합니다. | | 상품 탭이 완전히 채워짐 | 참여도가 0인 행을 포함하여 구성된 모든 동반 상품이 표시됩니다 (노출 수가 클릭 수 0인 행을 채움). | | 중복 제거가 작동 중임 | 동일한 노출/클릭을 다시 실행해도 집계가 일정하게 유지됩니다. | ## 문제 해결 (쇼핑 가능한 배너 관련 세부 사항) | 증상 | 해결 방법 | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | 필수 상품 이벤트가 도착하지 않음 | 배너가 다음 조건에 맞는지 확인하세요: Banner X 크리에이티브 단계에서 동반 상품과 함께 설정되었으며, 다음 항목이 `productImpression` 및 `productClick` 다음과 함께 실행됨: `productCode`/`catalogId`. | | 스크롤/다시 렌더링할 때마다 노출이 실행됨 | 하나 실행 `productImpression` 시급성 발생 시 상품당, 뷰어빌리티 발생당 하나씩 실행; 디바운스 적용. | | 상품 탭에 잘못되거나 누락된 상품이 표시됨 | 가능성이 높은 원인: `productCode`/`catalogId` 카탈로그와의 불일치 — 전송하는 ID를 카탈로그 피드와 대조하여 조정하세요. | | 장바구니 수량이 잘못됨 | 증분값을 전송하고 있습니다 — 절대적인 현재 수량을 전송하세요 `units`. | 일반적인 엔드포인트 문제 해결은 다음을 참조하세요: [광고 상호작용 이벤트 리포팅 기술 참조](https://help.citrusad.com/retail-media-interface/integration/ko/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/ko/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.