개발자 퀵스타트

이 가이드의 목표

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)**를 확인합니다.

AD Manager 접속 (https://{customer_id}.a2cloud.aiderx.app - Developer Portal과 동일 도메인)
지면 메뉴 클릭
테스트할 지면의 ID 복사

지면 ID는 광고 요청 URL에 사용됩니다. 지면이 활성화 상태인지 확인하세요.

Step 3: 광고 요청 보내기 (3분)

터미널에서 다음 curl 명령을 실행합니다.

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 응답을 받습니다:

{
  "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를 설치하면 더 간편하게 광고를 노출할 수 있습니다.

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <!-- 광고가 표시될 위치 -->
  <div id="a2-placement"></div>
  
  <!-- A2 SDK -->
  <script src="https://{customer_id}.a2cloud.aiderx.app/a2-sdk.js"></script>
  <script>
    // SDK 초기화
    // port 미지정 시 빌드 타임 기본값(VITE_PORT) 또는 8000 사용
    // 배포 환경에 따라 port 명시 필요할 수 있음
    let app = new A2_SDK.A2({
      base_url: "https://{customer_id}.a2cloud.aiderx.app"
    });
    
    // 사용자 등록 (선택)
    app.register_user({
      id: "user_123",
      yob: 1990,
      gender: "M"  // "M" | "F" | "O"
    });
    
    // 광고 등록
    // register_ad(tagid, element, width, height, responsive)
    // responsive: "fixed" (기본값) | "resized"
    // 주의: element는 반드시 존재해야 함 (널 체크는 SDK 상세 가이드 참조)
    let placement = document.getElementById("a2-placement");
    app.register_ad("your-tagid", placement, 300, 250, "fixed");
  </script>
</body>
</html>

완료! 🎉

첫 번째 광고 요청을 성공적으로 보냈습니다!

다음 단계

API 레퍼런스

전체 API 문서 및 상세 파라미터 확인하기

SDK 상세 가이드

SDK 고급 기능 및 커스터마이징 방법

이벤트 로그 연동

노출, 클릭, 전환 이벤트 전송하기

캠페인 관리 API

API로 캠페인 생성 및 관리하기

자주 묻는 질문

API 토큰은 언제 필요한가요?

광고 서빙 API (/app/v0/ad/{tagid})는 인증 없이 사용할 수 있습니다. 이 Quick Start에서 다루는 광고 요청에는 토큰이 필요 없습니다.API 토큰은 캠페인 관리 API (캠페인 생성, 수정, 삭제 등)에서만 필요합니다. 토큰 발급이 필요한 경우, ADM의 Settings 메뉴에서 발급받을 수 있습니다. 자세한 내용은 토큰 발급 가이드를 참조하세요.

광고가 없으면 어떤 응답이 오나요?

광고가 없으면 HTTP 204 상태 코드가 반환됩니다 (응답 바디는 무시됨). SDK를 사용하면 204를 NoBidError로 처리하여 광고가 표시되지 않습니다. SDK 초기화 시 collapse_nobid: true 옵션을 설정하면 광고 영역이 자동으로 숨겨집니다. 직접 API를 호출하는 경우, 204 상태 코드를 기준으로 no-bid 처리하세요 (바디에 의존하지 마세요).

노출 추적은 어떻게 하나요?

응답의 impression_url을 광고가 화면에 표시될 때 호출하세요. SDK를 사용하면 자동으로 처리됩니다.

클릭 추적은 어떻게 하나요?

사용자가 광고를 클릭하면 click_url로 리다이렉트하세요. A2가 자동으로 클릭을 추적한 후 최종 랜딩 페이지로 이동시킵니다.

Rate Limit이 있나요?

기본적으로 초당 100 요청까지 허용됩니다. 더 높은 한도가 필요하면 지원팀에 문의하세요.

문제 해결

401 Unauthorized

이 에러는 캠페인 관리 API에서만 발생합니다 (광고 서빙 API는 해당 없음)
광고 서빙 API (/app/v0/ad/{tagid})는 인증이 필요 없습니다 - 이 Quick Start에서 다루는 요청에는 401이 발생하지 않습니다
캠페인 관리 API 사용 시: ADM Settings에서 토큰 확인 (토큰 발급 가이드)

404 Not Found

지면 ID가 올바른지 확인하세요
지면이 활성화 상태인지 확인하세요

500 Internal Server Error

요청 JSON 형식이 올바른지 확인하세요
문제가 지속되면 지원팀에 문의하세요

시작하기

핵심 개념

지면 관리

캠페인 관리

배정 관리

분석 및 리포트

시스템 관리

이 가이드의 목표

사전 준비

Step 1: Developer Portal 접속 (1분)

Step 2: 지면 ID 확인 (2분)

Step 3: 광고 요청 보내기 (3분)

Step 4: 응답 확인 (2분)

Step 5: SDK 연동 (선택, 2분)

완료! 🎉

다음 단계

API 레퍼런스

SDK 상세 가이드

이벤트 로그 연동

캠페인 관리 API

자주 묻는 질문

문제 해결

401 Unauthorized

404 Not Found

500 Internal Server Error

​이 가이드의 목표

​사전 준비

​Step 1: Developer Portal 접속 (1분)

​Step 2: 지면 ID 확인 (2분)

​Step 3: 광고 요청 보내기 (3분)

​Step 4: 응답 확인 (2분)

​Step 5: SDK 연동 (선택, 2분)

​완료! 🎉

​다음 단계

API 레퍼런스

SDK 상세 가이드

이벤트 로그 연동

캠페인 관리 API

​자주 묻는 질문

​문제 해결

​401 Unauthorized

​404 Not Found

​500 Internal Server Error

이 가이드의 목표

사전 준비

Step 1: Developer Portal 접속 (1분)

Step 2: 지면 ID 확인 (2분)

Step 3: 광고 요청 보내기 (3분)

Step 4: 응답 확인 (2분)

Step 5: SDK 연동 (선택, 2분)

완료! 🎉

다음 단계

자주 묻는 질문

문제 해결

401 Unauthorized

404 Not Found

500 Internal Server Error