광고 이벤트·로그 연동

SDK 없이 광고 응답의 광고 추적 식별자(ext.ad_log)로 노출·클릭·전환을 기록하는 과정을 다룹니다. 연동된 광고 이벤트는 광고 성과를 확인하는 데 활용합니다. 광고 요청과 표시는 광고 송출 연동을 참고하세요. 상품 조회·구매 등의 사용자 행동 로그는 사용자 행동을 반영한 추천에 활용합니다. 광고 이벤트와 별도로 전송하는 사용자 행동 로그의 연결 방법은 상품·콘텐츠 데이터 연동을 참고하세요.

광고 이벤트 이해하기

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

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

광고 추적 식별자 보관

광고 요청으로 광고가 반환되면 응답의 최상위 ext.ad_log에 광고 추적 식별자가 함께 옵니다. 전체 응답 명세는 광고 요청 API를 참고하세요.

Response (일부)

{
  "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`

{
  "ad": {
    "display": {
      "banner": {
        "img": "https://cdn.example.com/banner.jpg"
      },
      "event": [
        { "url": "<노출 추적 URL>" }
      ]
    }
  }
}

{
  "ad": {
    "display": {
      "native": {
        "eventtrackers": [
          { "event": 1, "method": 1, "url": "<노출 추적 URL>" }
        ]
      }
    }
  }
}

네이티브의 eventtrackers에는 소재에 등록된 다른 추적 URL이 함께 들어 있을 수 있습니다. 조건에 맞는 URL을 모두 호출하세요. 광고 표시가 완료된 시점에 다음 코드를 한 번 실행합니다.

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 이미지가 반환됩니다.

노출 추적 URL이 응답에 없을 때

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

네이티브 광고를 HTML로 받는 경우

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

vimp를 별도로 전송해야 하나요?

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

클릭

사용자가 광고를 클릭하면 사용자 로그 기록 API에 action을 clk로 전송합니다. ad_log에는 클릭한 광고 응답의 ext.ad_log를 넣습니다.

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 옵션을 사용할 수 있습니다.

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에는 사용자 세션이나 주문 정보에 저장해 둔 값을 넣습니다.

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이나 동일한 클릭·전환 이벤트를 반복해서 전송하면 별도 이벤트로 집계될 수 있습니다.

이벤트가 리포트에 반영되었는지는 연동 검증과 문제 해결을 참고하세요.

시작하기

연동 가이드

광고 이벤트·로그 연동

광고 이벤트 이해하기

광고 추적 식별자 보관

이벤트 전송

노출

클릭

전환

전송 시 주의사항

​광고 이벤트 이해하기

​광고 추적 식별자 보관

​이벤트 전송

​노출

​클릭

​전환

​전송 시 주의사항

광고 이벤트 이해하기

광고 추적 식별자 보관

이벤트 전송

노출

클릭

전환

전송 시 주의사항