> ## 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.

# 광고 이벤트·로그 연동

> 광고 응답의 광고 추적 식별자로 노출·클릭·전환을 기록하고 성과를 집계하는 방법을 안내합니다.

SDK 없이 광고 응답의 광고 추적 식별자(`ext.ad_log`)로 노출·클릭·전환을 기록하는 과정을 다룹니다. 연동된 광고 이벤트는 광고 성과를 확인하는 데 활용합니다. 광고 요청과 표시는 [광고 송출 연동](https://docs.aiderx.io/development/ko/serving-ad.md)을 참고하세요.

상품 조회·구매 등의 사용자 행동 로그는 사용자 행동을 반영한 추천에 활용합니다. 광고 이벤트와 별도로 전송하는 사용자 행동 로그의 연결 방법은 [상품·콘텐츠 데이터 연동](https://docs.aiderx.io/development/ko/catalog.md)을 참고하세요.

## 광고 이벤트 이해하기

광고 이벤트는 광고 응답과 사용자의 반응, 목표 행동을 연결해 기록합니다.

| 이벤트 | 의미 |
| - | - |
| 노출 | 설정된 노출 추적 기준에 따라 광고가 노출된 것으로 기록된 횟수 |
| 클릭 | 사용자가 광고를 클릭한 횟수 |
| 전환 | 구매나 가입처럼 서비스에서 정한 목표 행동이 완료되어 전환으로 기록된 횟수 |

## 광고 추적 식별자 보관

광고 요청으로 광고가 반환되면 응답의 최상위 `ext.ad_log`에 광고 추적 식별자가 함께 옵니다. 전체 응답 명세는 [광고 요청 API](https://docs.aiderx.io/ko/0.5.0/decision/ad-serving/serving-an-ad.md)를 참고하세요.

```json Response (일부) theme={null}
{
  "ad": {
    "id": "7c4f2b18-e9a6-4d3f-b821-56a09c73e4fd"
  },
  "ext": {
    "message": "success",
    "ad_log": "<A2가 반환한 광고 추적 식별자>"
  }
}
```

`ad_log`는 광고 응답마다 발급되는 식별자로, 이벤트를 해당 광고 응답과 연결합니다. 광고 응답을 처리할 때 `ad`와 `ext.ad_log`를 함께 보관하세요. 서버에서 광고를 요청했다면 두 값을 클라이언트에 함께 전달합니다.

클릭에는 사용자가 선택한 광고 응답의 `ad_log`를 사용합니다. 전환이 나중에 발생한다면 같은 값을 사용자 세션이나 주문 정보에 저장했다가 전환이 확정될 때 사용합니다.

## 이벤트 전송

### 노출

노출은 배정에 설정된 기준에 따라 광고를 응답한 시점이나 클라이언트가 노출 추적 URL을 호출한 시점에 기록합니다.

| 노출 추적 방식 | 노출로 기록하는 시점 | 클라이언트 구현 |
| - | - | - |
| **광고 응답 기준** (기본값) | A2가 광고를 응답할 때 | 추가 구현 없음 |
| **노출 이벤트 기준** | 광고가 화면에 표시되어 클라이언트가 추적 URL을 호출할 때 | 응답의 노출 추적 URL 호출 |

노출 추적 방식은 배정의 **게재 설정**에서 선택합니다. Ad Manager의 **광고 > 광고 항목**에서 광고 항목을 선택하고, **인벤토리 배정** 탭에서 배정을 추가하거나 수정하세요.

**노출 이벤트 기준**을 선택하면 A2가 광고 응답에 노출 추적 URL을 추가합니다. URL이 들어가는 위치는 소재 유형에 따라 다릅니다.

| 소재 유형 | 노출 추적 URL 위치 |
| - | - |
| 이미지 배너 | `ad.display.event[]`의 `url` |
| 네이티브 | `ad.display.native.eventtrackers[]` 중 `event`가 `1`, `method`가 `1`인 항목의 `url` |

```json 이미지 배너 theme={null}
{
  "ad": {
    "display": {
      "banner": {
        "img": "https://cdn.example.com/banner.jpg"
      },
      "event": [
        { "url": "<노출 추적 URL>" }
      ]
    }
  }
}
```

```json 네이티브 theme={null}
{
  "ad": {
    "display": {
      "native": {
        "eventtrackers": [
          { "event": 1, "method": 1, "url": "<노출 추적 URL>" }
        ]
      }
    }
  }
}
```

네이티브의 `eventtrackers`에는 소재에 등록된 다른 추적 URL이 함께 들어 있을 수 있습니다. 조건에 맞는 URL을 모두 호출하세요.

광고 표시가 완료된 시점에 다음 코드를 한 번 실행합니다.

```javascript theme={null}
function getImpressionUrls(ad) {
  const native = ad?.display?.native;
  if (native) {
    return (native.eventtrackers ?? [])
      .filter((tracker) => tracker.event === 1 && tracker.method === 1 && tracker.url)
      .map((tracker) => tracker.url);
  }
  return (ad?.display?.event ?? []).map((event) => event.url).filter(Boolean);
}

getImpressionUrls(response.ad).forEach((url) => {
  new Image(1, 1).src = url;
});
```

정상적으로 호출되면 `200`과 1×1 이미지가 반환됩니다.

> [accordion] 노출 추적 URL이 응답에 없을 때
>
> 동영상 소재와 일부 외부 애드 네트워크 광고에는 노출 추적 URL이 포함되지 않으므로, 해당 광고를 배정할 때는 **광고 응답 기준**을 사용하세요. **노출 이벤트 기준**을 선택하면 노출이 집계되지 않습니다.

> [accordion] 네이티브 광고를 HTML로 받는 경우
>
> 네이티브 광고를 HTML 마크업(`ad.display.adm`)으로 받아도 노출 추적 URL은 `ad.display.native.eventtrackers`에 포함됩니다. 광고 단위에 적용된 네이티브 스타일의 HTML이 노출 추적 URL을 직접 호출하는지 확인하고, 호출하지 않는다면 위 코드로 호출하세요. 양쪽에서 모두 호출하면 노출이 중복 집계됩니다.

> [accordion] vimp를 별도로 전송해야 하나요?
>
> 광고 기본 연동에서는 `vimp`를 별도로 전송하지 않습니다. 광고 노출은 위에서 선택한 노출 추적 방식에 따라 `imp`로 기록됩니다. 로그 API는 `vimp` 요청을 받지만, 현재 광고 성과 집계에서는 기본 노출 수로 사용하지 않습니다. 추천의 조회 이벤트는 추천 연동 문서를 참고하세요.

### 클릭

사용자가 광고를 클릭하면 [사용자 로그 기록 API](https://docs.aiderx.io/ko/0.5.0/decision/ad-log/record-user-log.md)에 `action`을 `clk`로 전송합니다. `ad_log`에는 클릭한 광고 응답의 `ext.ad_log`를 넣습니다.

```bash theme={null}
curl -X POST "https://your_a2_service/dmp/v0/log" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ad_log",
    "action": "clk",
    "ad_log": "<클릭한 광고의 ext.ad_log>"
  }'
```

웹에서는 클릭 이벤트 전송을 시작한 뒤 랜딩 페이지를 여세요. 페이지 이동 중에도 요청을 이어가려면 Fetch API의 `keepalive` 옵션을 사용할 수 있습니다.

> [accordion] HTML 소재를 iframe으로 표시하는 경우
>
> iframe 안의 클릭은 부모 문서의 클릭 핸들러로 전달되지 않습니다. HTML 소재를 표시하고 랜딩 페이지를 여는 것만으로는 A2의 `clk` 이벤트가 자동으로 기록되지 않습니다.
>
> API 직접 연동에서는 소재나 광고 제공업체가 제공하는 클릭 알림을 부모 문서에서 받아, 해당 광고 응답의 `ext.ad_log`로 위 클릭 API를 호출하는 처리가 필요합니다. `postMessage`로 알림을 받는다면 메시지를 보낸 iframe과 출처를 확인한 뒤 처리하세요. 클릭 알림을 제공하지 않는 소재는 제공업체와 연결 방법을 확인해야 합니다.
>
> Web SDK로 네이티브 HTML 소재를 표시하는 경우에도 네이티브 스타일 HTML이 클릭 시 `parent.postMessage({ type: "ad-clicked", id: iframeId }, "*")`를 보내야 SDK가 `clk`를 전송합니다. `iframeId`는 SDK가 연결한 iframe의 ID와 일치해야 합니다. 이 메시지는 SDK의 클릭 연결 방식이므로, SDK 없이 표시할 때는 부모 문서의 메시지 수신과 클릭 API 호출을 직접 구현해야 합니다. SDK가 전송하는 클릭을 별도로 다시 전송하면 중복 집계될 수 있습니다.

### 전환

구매나 가입처럼 서비스에서 정한 전환이 확정되면 같은 API에 `action`을 `conv`로 전송합니다. `ad_log`에는 사용자 세션이나 주문 정보에 저장해 둔 값을 넣습니다.

```bash theme={null}
curl -X POST "https://your_a2_service/dmp/v0/log" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ad_log",
    "action": "conv",
    "ad_log": "<저장해 둔 ext.ad_log>"
  }'
```

## 전송 시 주의사항

* `ad_log`를 수정하거나 직접 만들면 이벤트가 원래 광고 응답과 연결되지 않아 집계에서 누락되거나 잘못 집계될 수 있습니다. 노출 추적 URL은 서명된 주소이므로 응답으로 받은 주소를 그대로 사용하세요.
* 같은 노출 추적 URL이나 동일한 클릭·전환 이벤트를 반복해서 전송하면 별도 이벤트로 집계될 수 있습니다.

이벤트가 리포트에 반영되었는지는 [연동 검증과 문제 해결](https://docs.aiderx.io/development/ko/integration-verification-and-troubleshooting.md)을 참고하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.