> ## 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.
# 개발자 퀵스타트
> 10분 안에 첫 광고 요청 보내기
## 이 가이드의 목표
10분 안에:
* ✅ 지면 ID 확인
* ✅ 첫 광고 요청 전송
* ✅ 광고 응답 확인
***
## 사전 준비
**필요한 것**:
* A2 계정 (Developer Portal 접근 권한)
* curl 또는 Postman
* 테스트용 지면 ID
***
## Step 1: Developer Portal 접속 (1분)
A2 Developer Portal에 접속합니다.
```
https://{customer_id}.a2cloud.aiderx.app/developers/
```
로그인 화면에서 **Developer Portal** 탭을 선택하세요. AD Manager와 동일한 계정으로 로그인할 수 있습니다.
***
## Step 2: 지면 ID 확인 (2분)
AD Manager에서 광고를 노출할 지면의 \*\*지면 ID (tagid)\*\*를 확인합니다.
1. AD Manager 접속 (`https://{customer_id}.a2cloud.aiderx.app` - Developer Portal과 동일 도메인)
2. **지면** 메뉴 클릭
3. 테스트할 지면의 **ID** 복사
지면 ID는 광고 요청 URL에 사용됩니다. 지면이 **활성화** 상태인지 확인하세요.
***
## Step 3: 광고 요청 보내기 (3분)
터미널에서 다음 curl 명령을 실행합니다.
```bash theme={null}
curl -X POST \
-H "Content-type: application/json" \
https://{customer_id}.a2cloud.aiderx.app/app/v0/ad/{tagid} \
-d '{
"version": "0.1.0",
"user": {
"id": "test_user_123"
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}
}'
```
**파라미터 설명**:
* `{customer_id}`: 고객사 ID
* `{tagid}`: 지면 ID (AD Manager에서 확인)
광고 서빙 API는 인증이 필요 없습니다. `device.ua` 필드는 권장 사항이며, 타겟팅 정확도 향상에 도움이 됩니다.
***
## Step 4: 응답 확인 (2분)
성공하면 다음과 같은 JSON 응답을 받습니다:
```json theme={null}
{
"version": "0.1.0",
"ad": {
"id": "ad_123456",
"display": {
"w": 300,
"h": 250,
"banner": {
"img": "https://example.com/ad-image.jpg"
}
}
},
"ext": {
"message": "success",
"ad_log": "encrypted_tracking_data..."
}
}
```
**응답 필드 설명**:
* `version`: API 버전 (예: `"0.1.0"`)
* `ad.id`: 광고 ID
* `ad.display.w`, `ad.display.h`: 광고 크기
* `ad.display.banner.img`: 배너 이미지 URL (또는 `ad.display.adm`에 HTML 마크업이 올 수 있음)
* `ext.message`: 응답 상태 메시지
* `ext.ad_log`: 추적용 암호화 데이터 (SDK가 자동 처리)
***
## Step 5: SDK 연동 (선택, 2분)
웹사이트에 SDK를 설치하면 더 간편하게 광고를 노출할 수 있습니다.
```html theme={null}
My Website
```
***
## 완료! 🎉
첫 번째 광고 요청을 성공적으로 보냈습니다!
### 다음 단계
전체 API 문서 및 상세 파라미터 확인하기
SDK 고급 기능 및 커스터마이징 방법
노출, 클릭, 전환 이벤트 전송하기
API로 캠페인 생성 및 관리하기
***
## 자주 묻는 질문
**광고 서빙 API** (`/app/v0/ad/{tagid}`)는 인증 없이 사용할 수 있습니다. 이 Quick Start에서 다루는 광고 요청에는 토큰이 필요 없습니다.
API 토큰은 **캠페인 관리 API** (캠페인 생성, 수정, 삭제 등)에서만 필요합니다. 토큰 발급이 필요한 경우, ADM의 Settings 메뉴에서 발급받을 수 있습니다. 자세한 내용은 [토큰 발급 가이드](/development/tutorial/ko/get-token)를 참조하세요.
광고가 없으면 HTTP 204 상태 코드가 반환됩니다 (응답 바디는 무시됨). SDK를 사용하면 204를 `NoBidError`로 처리하여 광고가 표시되지 않습니다. SDK 초기화 시 `collapse_nobid: true` 옵션을 설정하면 광고 영역이 자동으로 숨겨집니다. 직접 API를 호출하는 경우, 204 상태 코드를 기준으로 no-bid 처리하세요 (바디에 의존하지 마세요).
응답의 `impression_url`을 광고가 화면에 표시될 때 호출하세요. SDK를 사용하면 자동으로 처리됩니다.
사용자가 광고를 클릭하면 `click_url`로 리다이렉트하세요. A2가 자동으로 클릭을 추적한 후 최종 랜딩 페이지로 이동시킵니다.
기본적으로 초당 100 요청까지 허용됩니다. 더 높은 한도가 필요하면 지원팀에 문의하세요.
***
## 문제 해결
### 401 Unauthorized
* 이 에러는 **캠페인 관리 API**에서만 발생합니다 (광고 서빙 API는 해당 없음)
* 광고 서빙 API (`/app/v0/ad/{tagid}`)는 인증이 필요 없습니다 - 이 Quick Start에서 다루는 요청에는 401이 발생하지 않습니다
* 캠페인 관리 API 사용 시: ADM Settings에서 토큰 확인 ([토큰 발급 가이드](/development/tutorial/ko/get-token))
### 404 Not Found
* 지면 ID가 올바른지 확인하세요
* 지면이 활성화 상태인지 확인하세요
### 500 Internal Server Error
* 요청 JSON 형식이 올바른지 확인하세요
* 문제가 지속되면 지원팀에 문의하세요