메인 콘텐츠로 건너뛰기

​
이 가이드의 목표

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 명령을 실행합니다. 
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 (/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가 자동으로 클릭을 추적한 후 최종 랜딩 페이지로 이동시킵니다.
기본적으로 초당 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 형식이 올바른지 확인하세요
  • 문제가 지속되면 지원팀에 문의하세요