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

# 연동 검증과 문제 해결

> 구현한 연동이 맞게 집계되는지 확인하고 문제 발생 지점을 찾는 방법을 안내합니다.

이 문서에서는 구현한 연동이 맞게 집계되는지 확인하고, 문제가 생겼을 때 원인을 찾는 방법을 다룹니다.

## 집계로 연동 결과 확인

개별 이벤트를 조회하는 기능이 없어 연동이 맞게 동작하는지는 집계 수치로 판단합니다. 다른 트래픽이 섞이면 결과를 구분할 수 없으므로 검증용 광고 단위에서 정해진 횟수만큼 실행하세요.

**1. 기준값 기록**

**분석 > 광고 인벤토리 분석 > 광고 단위 분석**에서 검증용 광고 단위의 현재 노출·클릭 수를 기록하고, 배정의 **노출 추적 방식**을 확인합니다.

**2. 정해진 횟수만큼 실행**

구현한 서비스에서 광고를 표시하고 클릭합니다. 광고 요청, 노출 추적 URL 호출, 클릭 이벤트 전송이 각각 몇 번 발생했는지 기록하고, 확인을 위해 이미 보낸 이벤트를 다시 보내지 마세요.

**3. 집계 확인**

1분 정도 지난 뒤 광고 단위 분석 페이지를 브라우저에서 다시 불러와 기록해 둔 값과 비교합니다.

| 지표 | 기대 증가량 |
| - | - |
| 노출 | **광고 응답 기준**은 광고가 반환된 요청 수, **노출 이벤트 기준**은 노출 추적 URL 호출 수 |
| 클릭 | 클릭 이벤트 전송 수 |
| 전환 | 전환 이벤트 전송 수(전환 연동을 사용하는 경우) |

이벤트 API의 HTTP `200`은 요청을 받았다는 뜻이며, 집계가 끝났다는 뜻은 아닙니다. 기본 설정에서는 이벤트가 보통 1분 안에 집계에 반영되고, 광고 단위 분석은 한국 시간 기준으로 날짜를 나눕니다. 페이지를 다시 불러와도 지표가 늘지 않으면 아래 자주 묻는 문제를 확인하고, 원인을 찾지 못하면 지원 요청에 필요한 정보를 준비해 문의하세요.

## 자주 묻는 문제

> [accordion] 광고 요청에 HTTP 204가 반환돼요
>
> 정상적인 광고 없음 응답입니다. 접속과 광고 없음 처리는 확인되었지만, 광고 표시와 클릭은 아직 검증되지 않은 상태입니다. 송출 가능한 광고로 검증하려면 다음을 확인하세요.
>
> * 요청 경로의 `tagid`가 광고 단위 ID와 같은지
> * 광고 단위에 송출 가능한 광고가 배정되어 있는지
> * 요청에 넣은 `targeting`이나 `ad_size`가 설정과 일치하는지
>
> 송출 조건은 [광고가 송출되지 않을 때 확인할 설정](https://docs.aiderx.io/development/ko/serving-ad.md#no-ad-checklist)을 참고하세요.

> [accordion] 광고 요청에 4xx나 5xx가 반환돼요
>
> `400`, `415`, `422`는 요청 형식 오류입니다. `Content-Type: application/json` 헤더와 JSON 본문을 확인하세요.
>
> 현재 버전에서는 광고 단위 ID의 형식이 잘못되었거나 해당 광고 단위가 없을 때도 `500`이 반환되므로 `tagid`를 먼저 확인합니다. 같은 요청에서 `5xx`가 반복되면 발생 시각과, 응답에 포함된 경우 `x-request-id`를 기록해 두세요.

> [accordion] curl은 성공하는데 브라우저에서는 요청이 실패해요
>
> 브라우저 개발자 도구의 Console과 Network 탭에서 다음 오류를 확인하세요.
>
> * CORS 오류: 프록시나 배포 설정에서 페이지 주소(Origin)를 제한함(A2 기본 설정은 모든 Origin을 허용)
> * 사전 요청(`OPTIONS`) 실패: 프록시나 방화벽이 사전 요청을 막음
> * 혼합 콘텐츠: HTTPS 페이지에서 HTTP 주소의 A2를 호출함
>
> 배포 담당자에게 문의할 때는 페이지 주소, 요청 URL, Console의 오류 메시지를 함께 전달하세요.

> [accordion] 응답은 왔는데 광고가 표시되지 않아요
>
> HTTP `200` 응답에 `ad`가 있는지 먼저 확인합니다. `ad`가 없고 `ext.passback`이 있다면 광고 단위에 설정된 대체 광고 태그가 반환된 것입니다. 처리 방법은 [광고 송출 연동](https://docs.aiderx.io/development/ko/serving-ad.md)의 광고 없음 처리를 참고하세요.
>
> `ad`가 있다면 소재 유형에 맞는 필드를 사용했는지 확인합니다.
>
> * 이미지 배너: `ad.display.banner`
> * 네이티브: `ad.display.native`
> * HTML 마크업: `ad.display.adm`
>
> 필드가 맞다면 브라우저 개발자 도구에서 이미지나 HTML 요청이 실패했는지, Console 오류가 있는지 확인하세요.

> [accordion] 광고를 클릭하면 이동은 되는데 클릭 수가 늘지 않아요
>
> 랜딩 페이지 이동과 클릭 이벤트 전송은 따로 동작합니다. 클릭한 광고 응답의 `ext.ad_log`를 그대로 넣고 `action`을 `clk`로 보냈는지 확인하세요. 다른 광고 응답의 `ad_log`를 쓰거나 값을 바꾸면 해당 광고와 연결되지 않습니다.
>
> 웹에서 페이지가 이동하면서 요청이 취소된다면 Fetch API의 `keepalive`를 사용하거나 서버에서 이벤트를 보내세요. 전송 시점과 예제는 [광고 이벤트·로그 연동](https://docs.aiderx.io/development/ko/ad-events-and-logs.md)을 참고하세요.

> [accordion] 이벤트 전송은 성공했는데 리포트에 반영되지 않아요
>
> 이벤트 API의 HTTP `200`은 요청을 받았다는 뜻이며, 집계까지 끝났다는 뜻은 아닙니다. 요청한 시각과 `action`, `ad_log`가 맞는지 확인하세요. 그런 다음 1분 정도 지나 **광고 단위 분석** 페이지를 브라우저에서 다시 불러오고, 같은 광고 단위와 날짜를 선택해 확인합니다.

> [accordion] 노출 수가 집계되지 않아요
>
> 배정의 **노출 추적 방식**을 확인하세요.
>
> * **광고 응답 기준**: A2가 광고 응답을 반환할 때 노출을 기록합니다.
> * **노출 이벤트 기준**: 클라이언트가 응답의 노출 추적 URL을 호출해야 노출이 기록됩니다.

> [accordion] 서비스 기록과 A2 집계가 달라요
>
> 두 결과가 같은 광고 단위와 기간, 이벤트 발생 조건을 기준으로 하는지 확인합니다. 서비스에서 클릭을 기록했더라도 A2 이벤트 요청이 취소되거나 실패하면 A2 클릭 수에는 반영되지 않습니다.
>
> 차이를 조사할 때는 일정 구간의 서비스 기록에서 발생 시각, 이벤트 종류, `tagid`, `ad_log`를 추려 A2 지표와 비교하세요. 검증용 광고 단위에서 한 건씩 재현하면 원인을 찾기 쉽습니다.

> [accordion] 같은 이벤트를 여러 번 보내면 어떻게 되나요?
>
> A2는 동일 이벤트의 중복 전송을 자동으로 제거하지 않습니다. 정상 처리된 중복 요청은 각각 집계될 수 있으므로, 하나의 이벤트를 반복 전송하지 않도록 구현하세요. 같은 노출 추적 URL을 여러 번 호출하는 경우도 마찬가지입니다.
>
> 사용자가 실제로 광고를 여러 번 클릭했다면 클릭마다 이벤트를 보냅니다. 재시도나 코드 중복으로 같은 클릭을 두 번 보내지 않도록 하세요.

> [accordion] 개별 이벤트가 수집되었는지 조회할 수 있나요?
>
> 개별 이벤트의 수집 상태를 조회하는 화면이나 API는 제공되지 않습니다. **광고 단위 분석**에서 지표가 증가했는지로 확인하세요. 위 항목을 모두 확인했는데도 지표가 늘지 않으면 아래 정보를 준비해 A2 담당자에게 문의하세요.

## 운영 적용 전 확인

| 확인 항목 | 완료 기준 |
| - | - |
| 주소와 권한 | 운영 A2 주소를 사용하고, 인증이 필요한 API의 토큰은 서버에만 보관함 |
| 식별자 | 운영 광고 단위 ID를 `tagid`로 사용하고 검증용 ID가 남아 있지 않음 |
| 광고 없음 | HTTP `204`와 passback 응답에서 광고 영역을 숨기거나 기본 콘텐츠를 표시함 |
| 요청 실패 | 타임아웃과 `4xx`·`5xx`에서 기존 화면을 유지함 |
| 소재 표시 | 사용하는 소재 유형별 로딩 실패와 클릭 동작을 확인함 |
| 광고 추적 식별자 전달 | 광고 응답의 `ad`와 `ext.ad_log`를 함께 보관·전달함 |
| 이벤트 전송 | 노출 추적 방식에 맞게 노출을 기록하고, 하나의 클릭·전환을 반복 전송하지 않음 |
| 집계 확인 | 검증용 광고 단위에서 노출·클릭 수와, 전환 연동을 사용한다면 전환 수가 실행한 횟수만큼 증가함 |

## 지원 요청에 필요한 정보

문제를 재현한 직후 다음 정보를 준비하면 요청부터 집계까지 어느 단계에서 문제가 발생했는지 확인하기 쉽습니다.

| 구분 | 준비할 정보 |
| - | - |
| 환경 | A2 주소의 호스트명, 테스트·운영 환경 구분, 사용 중인 A2 버전 |
| 발생 시각 | 날짜, 시각, 시간대와 발생 빈도 |
| 재현 절차 | 실행 순서, 기대 결과, 실제 결과 |
| 요청 | HTTP 메서드와 경로, 민감정보를 제거한 헤더·본문 |
| 응답 | HTTP 상태, 응답 본문, 응답에 포함된 `x-request-id` |
| 광고·추적 식별 정보 | `tagid`, 응답의 `ad.id`, `ext.ad_log`, 문제가 발생한 이벤트 종류 |
| 실행 환경 | 서버·웹·앱 구분, 브라우저나 앱 버전, 관련 콘솔·네트워크 오류 |

액세스 토큰, 비밀번호, 쿠키, 사용자 식별자와 개인정보는 제거하세요. `ad_log`는 문제의 광고 응답과 이벤트를 연결하는 데 필요할 수 있으므로 공개된 채널에 올리지 말고 담당자가 요청하면 합의된 비공개 채널로 전달하세요.


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