> ## Documentation Index > Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt > Use this file to discover all available pages before exploring further. # 광고 이벤트 기록 > 광고 또는 추천 이벤트를 기록합니다. `type`에 따라 요청 형식을 선택하며, 광고와 추천 이벤트는 서로 다른 추적 토큰을 사용합니다. ### 광고 이벤트 (`type: "ad_log"`) 광고 응답의 `ext.ad_log`를 변경 없이 복사해 `ad_log`에 넣습니다. `action`에 따라 기록되는 이벤트와 선택 필드의 의미가 달라집니다. | `action` | 의미 및 처리 | | --- | --- | | `imp` | 노출입니다. 할당의 `ad_log_tracking_mode`가 기록 시점을 결정합니다. `on_ad_response`는 A2 서버가 광고 응답을 반환할 때 기록합니다. `on_event_tracker`는 지원되는 소재의 응답에 트래커 URL을 포함하고, 클라이언트가 광고 표시 시 이 URL을 호출하면 A2가 요청을 받아 기록합니다. 같은 `imp`를 Log API에 중복 제출하지 마세요. | | `vimp` | 가시 노출 이벤트입니다. 설정된 `imp` 추적 모드와 별개이며, 현재 A2 Web SDK가 자동 전송하지 않습니다. | | `clk` | 클릭입니다. A2 Web SDK는 기본적으로 이 액션에 `price`를 포함하지 않습니다. | | `conv` | 전환입니다. `conversion_data.sales`는 전환 매출이고 `price`는 광고 비용입니다. | `price`는 이벤트에 추가로 반영할 광고 비용입니다. A2가 추적하는 노출의 비용은 자동 기록되므로 해당 비용에 `price`를 다시 지정하지 마세요. 광고 응답만으로 A2가 추적할 수 없는 전환 수수료 같은 비용에만 `price`를 지정하고, A2가 이미 기록한 비용을 다시 보고하지 마세요. 다운스트림 광고 지표는 전달된 `price`를 비용(spend)에 합산합니다. `conversion_data.sales`는 `conv`의 전환 매출이며 비용과 별도입니다. ```json {"type":"ad_log","action":"clk","ad_log":"<광고 응답의 ext.ad_log>"} ``` ### 추천 이벤트 (`type: "reco_log"`) 추천 응답의 `tracking_token`을 변경 없이 복사하고, 대상 항목 ID는 `event_items`에, 위치는 `event_position`에 넣습니다. `imp`의 경우 `on_ad_response`는 응답에 항목과 추적 토큰이 있을 때 기록하고, `on_event_tracker`는 클라이언트가 추천 항목이 표시됐다고 보고할 때 기록합니다. 추천 추적 모드는 응답의 `ext.ad_log_tracking_mode`에서 확인할 수 있습니다. ```json {"type":"reco_log","action":"clk","tracking_token":"<추천 응답의 tracking_token>","event_items":["catalog-item-123"],"event_position":[0]} ``` 요청은 다운스트림 처리를 위해 수신됩니다. 수신 성공만으로 이벤트가 기록됐다고 보장하지는 않습니다. `type`은 `"ad_log"`로 보냅니다. 광고 응답의 `ext.ad_log`를 변경 없이 복사해 `ad_log`에 넣습니다. `action`에 따라 기록되는 이벤트와 선택 필드의 의미가 달라집니다. | `action` | 의미 및 처리 | | - | - | | `imp` | 노출입니다. 할당의 `ad_log_tracking_mode`가 기록 시점을 결정합니다. `on_ad_response`는 A2 서버가 광고 응답을 반환할 때 기록합니다. `on_event_tracker`는 지원되는 소재의 응답에 트래커 URL을 포함하고, 클라이언트가 광고 표시 시 이 URL을 호출하면 A2가 요청을 받아 기록합니다. 같은 `imp`를 Log API에 중복 제출하지 마세요. | | `vimp` | 가시 노출 이벤트입니다. 설정된 `imp` 추적 모드와 별개이며, 현재 A2 Web SDK가 자동 전송하지 않습니다. | | `clk` | 클릭입니다. A2 Web SDK는 기본적으로 이 액션에 `price`를 포함하지 않습니다. | | `conv` | 전환입니다. `conversion_data.sales`는 전환 매출이고 `price`는 광고 비용입니다. | `price`는 이벤트에 추가로 반영할 광고 비용입니다. A2가 추적하는 노출의 비용은 자동 기록되므로 해당 비용에 `price`를 다시 지정하지 마세요. 광고 응답만으로 A2가 추적할 수 없는 전환 수수료 같은 비용에만 `price`를 지정하고, A2가 이미 기록한 비용을 다시 보고하지 마세요. 다운스트림 광고 지표는 전달된 `price`를 비용(spend)에 합산합니다. `conversion_data.sales`는 `conv`의 전환 매출이며 비용과 별도입니다. ```bash cURL theme={null} curl --request POST \ --url https://your_a2_service/dmp/v0/log \ --header 'Content-Type: application/json' \ --data '{"type":"ad_log","action":"clk","ad_log":"<광고 응답의 ext.ad_log>"}' ``` ## OpenAPI ````yaml openapi/decision.api.ko-dev.json POST /dmp/v0/log openapi: 3.1.0 info: contact: email: a2support@aiderx.io name: A2 Support url: https://aiderx.io description: |- ### 소개 Decision API는 사용자 요청 또는 컨텍스트 정보를 바탕으로 광고나 콘텐츠를 실시간으로 선택하고 배포합니다. 빠른 응답과 동적 기능을 통해 최적의 광고 또는 추천을 제공하여 사용자가 가능한 가장 높은 가치를 얻도록 합니다. 다양한 알고리즘, 머신러닝 모델 및 규칙 기반 로직을 적용할 수 있어 시스템이 끊임없이 변하는 조건에 유연하게 적응할 수 있습니다. title: Decision API version: dev x-logo: altText: A2 Logo url: >- https://cdn.prod.website-files.com/668de9e1f25ab5675d87758d/6690cf1bdce95af5e3522c25_a2_logo_800_250.png servers: [] security: [] tags: - description: 광고 요청, 캐시 설정 및 광고 제공 모듈의 기타 매개변수를 구성하기 위한 API입니다. name: Ad Serving - description: 추천 요청을 위한 API name: Recommendation Serving - description: >- 광고 제공 서버의 캐시를 조작하기 위한 API입니다. ### **중요** Serving 서버의 광고 또는 추천 관련 캐시 데이터를 직접 조작하는 경우 Ad Manager에서 광고 또는 추천 데이터를 함께 수정하지 않는 것을 **강력히 권장합니다.** 대신 모든 광고 또는 추천 데이터 변경은 Ad Manager API를 통해 처리하는 것을 **권장합니다.** Serving 서버에서 변경한 내용은 Ad Manager에 반영되지 않으므로 **데이터 무결성**이 손상될 수 있습니다. name: Cache Management - description: 광고 서빙 서버 설정 API name: Configuration - description: 광고 또는 추천과 관련된 전환, 노출 및 클릭 로그를 수신하는 API입니다. name: Ad Log paths: /dmp/v0/log: post: tags: - Ad Log summary: 사용자 로그 기록 description: >- 광고 또는 추천 이벤트를 기록합니다. `type`에 따라 요청 형식을 선택하며, 광고와 추천 이벤트는 서로 다른 추적 토큰을 사용합니다. ### 광고 이벤트 (`type: "ad_log"`) 광고 응답의 `ext.ad_log`를 변경 없이 복사해 `ad_log`에 넣습니다. `action`에 따라 기록되는 이벤트와 선택 필드의 의미가 달라집니다. | `action` | 의미 및 처리 | | --- | --- | | `imp` | 노출입니다. 할당의 `ad_log_tracking_mode`가 기록 시점을 결정합니다. `on_ad_response`는 A2 서버가 광고 응답을 반환할 때 기록합니다. `on_event_tracker`는 지원되는 소재의 응답에 트래커 URL을 포함하고, 클라이언트가 광고 표시 시 이 URL을 호출하면 A2가 요청을 받아 기록합니다. 같은 `imp`를 Log API에 중복 제출하지 마세요. | | `vimp` | 가시 노출 이벤트입니다. 설정된 `imp` 추적 모드와 별개이며, 현재 A2 Web SDK가 자동 전송하지 않습니다. | | `clk` | 클릭입니다. A2 Web SDK는 기본적으로 이 액션에 `price`를 포함하지 않습니다. | | `conv` | 전환입니다. `conversion_data.sales`는 전환 매출이고 `price`는 광고 비용입니다. | `price`는 이벤트에 추가로 반영할 광고 비용입니다. A2가 추적하는 노출의 비용은 자동 기록되므로 해당 비용에 `price`를 다시 지정하지 마세요. 광고 응답만으로 A2가 추적할 수 없는 전환 수수료 같은 비용에만 `price`를 지정하고, A2가 이미 기록한 비용을 다시 보고하지 마세요. 다운스트림 광고 지표는 전달된 `price`를 비용(spend)에 합산합니다. `conversion_data.sales`는 `conv`의 전환 매출이며 비용과 별도입니다. ```json {"type":"ad_log","action":"clk","ad_log":"<광고 응답의 ext.ad_log>"} ``` ### 추천 이벤트 (`type: "reco_log"`) 추천 응답의 `tracking_token`을 변경 없이 복사하고, 대상 항목 ID는 `event_items`에, 위치는 `event_position`에 넣습니다. `imp`의 경우 `on_ad_response`는 응답에 항목과 추적 토큰이 있을 때 기록하고, `on_event_tracker`는 클라이언트가 추천 항목이 표시됐다고 보고할 때 기록합니다. 추천 추적 모드는 응답의 `ext.ad_log_tracking_mode`에서 확인할 수 있습니다. ```json {"type":"reco_log","action":"clk","tracking_token":"<추천 응답의 tracking_token>","event_items":["catalog-item-123"],"event_position":[0]} ``` 요청은 다운스트림 처리를 위해 수신됩니다. 수신 성공만으로 이벤트가 기록됐다고 보장하지는 않습니다. requestBody: content: application/json: schema: $ref: '#/components/schemas/LogType' required: true responses: '200': description: 다운스트림 처리를 위해 요청을 수신했습니다. security: - '': [] components: schemas: LogType: oneOf: - allOf: - $ref: '#/components/schemas/AdLog' properties: type: const: ad_log type: string required: - type title: Ad event type: object - allOf: - $ref: '#/components/schemas/RecommendationLog' properties: type: const: reco_log type: string required: - type title: Recommendation event type: object AdLog: examples: - action: clk ad_log: type: ad_log properties: action: allOf: - $ref: '#/components/schemas/ActionType' description: 이벤트 종류입니다. 각 이벤트에 action을 명시적으로 전송하세요. ad_log: description: 필수 광고 추적 토큰입니다. 광고 응답의 ext.ad_log 값을 변경 없이 복사하세요. type: string conversion_data: anyOf: - $ref: '#/components/schemas/ConversionData' - type: 'null' description: >- 선택적 전환 데이터입니다. action=conv일 때 다운스트림 지표는 sales를 전환 매출로 읽으며 price/비용과 구분합니다. 구매 금액은 광고 비용이기도 한 경우가 아니라면 price로 보내지 마세요. custom_targeting: additionalProperties: true description: 다운스트림 광고 로그 처리로 전달되는 선택적 custom targeting 속성 type: - object - 'null' price: description: >- 이벤트에 추가로 반영할 선택적 광고 비용입니다. A2가 추적하는 노출의 비용은 자동 기록되므로 해당 비용에 `price`를 다시 지정하지 마세요. 광고 응답만으로 A2가 추적할 수 없는 전환 수수료 같은 비용에만 `price`를 지정하고, A2가 이미 기록한 비용을 다시 보고하지 마세요. 다운스트림 광고 지표는 전달된 `price`를 비용(spend)에 합산합니다. 전환 매출(conversion_data.sales)과는 별개입니다. format: double type: - number - 'null' timestamp_in_ms: description: >- 선택적 이벤트 시각입니다. Unix 타임스탬프를 정수 밀리초로 전송합니다. 생략하면 광고 로그 처리 시점의 시각을 사용합니다. format: int64 type: integer required: - action - ad_log type: object RecommendationLog: examples: - action: clk event_items: - catalog-item-123 event_position: - 0 timestamp_in_ms: 1760000000000 tracking_token: type: reco_log properties: action: allOf: - $ref: '#/components/schemas/ActionType' description: 이벤트 종류입니다. 각 이벤트에 action을 명시적으로 전송하세요. event_items: description: >- 이벤트 대상 항목의 카탈로그 ID 문자열 배열입니다. 필드 자체는 선택적이지만 추천 상호작용 이력을 기록하려면 event_items와 추적 토큰 내 사용자 ID가 필요합니다. 클릭한 항목이나 vimp 시 실제 보인 항목 등 해당 이벤트의 대상만 전송하세요. items: type: string type: - array - 'null' event_position: description: >- 이벤트 대상 항목의 슬롯 위치 배열입니다. 추천 응답의 position을 복사한 0 이상의 정수입니다. 슬롯별 지표에 사용하며 생략하면 해당 처리의 슬롯 목록은 비어 있습니다. items: format: uint64 minimum: 0 type: integer type: - array - 'null' seed_item_id: description: 추천 요청에서 시드 항목을 사용한 경우에 넣는 선택적 시드 항목 ID입니다. 빈 문자열은 사용하지 마세요. type: - string - 'null' timestamp_in_ms: description: >- 선택적 이벤트 시각입니다. 양의 정수 Unix 타임스탬프를 밀리초로 전송하세요. 값이 없거나 유효하지 않으면 추천 로그 처리에서는 수집 시각을 사용합니다. format: int64 type: - integer - 'null' tracking_token: description: >- 필수 추천 추적 토큰입니다. 추천 응답의 tracking_token 값을 변경 없이 복사하세요. 광고 응답의 ext.ad_log와는 다른 토큰입니다. type: string required: - action - tracking_token type: object ActionType: oneOf: - const: clk description: '클릭 이벤트: 사용자가 광고 또는 추천 항목을 클릭할 때 기록됩니다.' title: clk type: string - const: vimp description: '조회 가능 노출 이벤트: 광고 또는 추천 항목이 사용자에게 실제로 보일 때 기록합니다.' title: vimp type: string - const: imp description: 다운스트림 처리에서 허용되는 노출 이벤트입니다. title: imp type: string - const: conv description: >- 전환 이벤트: 광고를 본 후 사용자가 가치 있는 작업을 수행할 때 기록됩니다. 전환은 비즈니스 목표에 따라 정의할 수 있습니다. 전환 활동의 예: * 상품 구매 * 장바구니 추가 * 애플리케이션 설치 * 서비스 구독 * 파일 다운로드 * 링크 클릭 * 시간 제한 콘텐츠 소비 광고 목표에 따라 의미 있는 사용자 행동을 전환으로 정의할 수 있습니다. title: conv type: string ConversionData: properties: sales: anyOf: - $ref: '#/components/schemas/ConversionSales' - type: 'null' description: action=conv일 때 집계하는 전환 매출입니다. 다운스트림 지표는 JSON 숫자 또는 숫자 문자열을 허용합니다. type: object ConversionSales: anyOf: - format: double title: number type: number - title: string type: string ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.