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

# Quick Start

> 이미지 배너를 요청해 표시하고 클릭 이벤트가 수집되는지 확인합니다.

A2에서 광고를 받아 화면에 표시하고 클릭을 기록하는 과정을 직접 실행해 봅니다. 이미지 배너를 사용하는 웹 예제로 광고 응답과 광고 추적 식별자의 관계를 살펴보고, Ad Manager에서 클릭 수가 증가하는 것까지 확인합니다.

이 실습에서는 배너를 클릭해 이동을 확인한 뒤, 터미널에서 클릭 이벤트를 한 번 전송합니다. 웹 페이지의 클릭 동작과 이벤트 전송을 자동으로 연결하는 구현은 [광고 이벤트·로그 연동](https://docs.aiderx.io/development/ko/ad-events-and-logs.md)을 참고하세요.

> [accordion] API 직접 연동과 Web SDK 비교
>
> A2는 Decision API를 직접 호출하거나 Web SDK를 사용해 광고를 연동할 수 있습니다. 앱이나 서버 환경에서도 사용할 수 있고 처리 방식을 직접 제어할 수 있는 API 직접 연동을 기본 경로로 안내합니다.
>
> | 구분 | API 직접 연동 | Web SDK 연동 |
> | - | - | - |
> | 사용 환경 | 서버, 웹, 앱 | 웹 브라우저 |
> | 광고 요청 | 요청 시점과 본문을 직접 구성 | `register_ad` 호출 시 SDK가 요청 |
> | 광고 표시 | 소재 유형별 화면을 직접 구현 | 이미지 배너와 HTML 마크업 소재를 광고 영역에 표시하고, 옵션에 따라 광고가 없으면 영역을 숨김 |
> | 이벤트 | 설정에 따라 필요한 노출 추적과 클릭·전환 전송을 직접 구현 | 이미지 배너를 클릭하면 SDK가 클릭 이벤트를 자동으로 전송 |
> | 적합한 경우 | 앱, 서버 경유, 자체 UI, 세밀한 예외 처리 | 제공된 SDK 번들을 사용하는 일반적인 웹 광고 영역 |
>
> Web SDK는 브라우저의 DOM과 `localStorage`를 사용하므로 앱이나 서버에서 같은 방식으로 사용할 수 없습니다. 제공되는 SDK 빌드와 설정은 환경마다 다를 수 있으므로 적용 전에 사용 가능한 번들과 옵션을 확인하세요. Web SDK 설치와 사용 방법은 별도 문서로 준비하고 있습니다.

## 실습 준비

실습에는 액세스 토큰이 필요 없습니다. 시작하기 전에 다음 항목을 준비하세요.

* **A2 접속 주소**: [API 접속과 인증](https://docs.aiderx.io/development/ko/api-access-and-auth.md)에서 확인합니다.
* **광고 단위**: 광고를 표시할 영역인 광고 단위에 이미지 배너 소재가 연결된 광고가 배정되어 있고, 현재 송출할 수 있어야 합니다. 결과를 다른 트래픽과 구분할 수 있도록 검증용 광고 단위를 사용하세요.
* **광고 설정**: 맞춤 타겟팅 없이 빈 요청 `{}`으로 선택될 수 있어야 하며, 배정의 **노출 추적 방식**이 **광고 응답 기준**(기본값)이어야 합니다.
* **Ad Manager 계정**: 광고 단위 ID 확인과 광고 단위 분석 조회에 관리자 또는 운영자 계정이 필요합니다.
* **실행 도구**: curl, 텍스트 편집기, 웹 브라우저, 로컬 웹 서버를 실행할 Python 3

준비된 광고 단위가 없다면 광고 운영 담당자에게 요청하세요. 설정 방법은 [지면 생성 및 관리](https://docs.aiderx.io/guides/for-retailers/ko/placement.md), [배정 요청](https://docs.aiderx.io/guides/for-advertisers/ko/allocation-request.md), [배정 검토](https://docs.aiderx.io/guides/for-retailers/ko/allocation-review.md)를 참고하세요.

광고 단위가 준비되면 요청에 사용할 ID를 확인합니다.

**1. 광고 단위 선택하기**

Ad Manager의 **인벤토리 > 광고 단위**에서 광고를 요청할 광고 단위를 선택합니다.

**2. 설정 탭 열기**

광고 단위 상세 화면에서 **설정** 탭을 선택합니다.

**3. 광고 단위 ID 복사하기**

**기본 정보**의 **ID**를 복사합니다.

**광고 응답 기준**에서는 A2가 광고를 선택해 응답을 생성하는 과정에서 노출을 기록하므로, 예제에서는 노출 이벤트를 따로 보내지 않습니다. 다른 추적 방식을 사용한다면 [광고 이벤트·로그 연동](https://docs.aiderx.io/development/ko/ad-events-and-logs.md)을 참고하세요.

실습을 시작하기 전에 Ad Manager의 **분석 > 광고 인벤토리 분석 > 광고 단위 분석**에서 선택한 광고 단위의 오늘 클릭 수를 확인해 두세요.

예제에서는 다음 두 값을 바꿉니다.

| 예제 값 | 바꿀 값 |
| - | - |
| `https://your_a2_service` | A2 접속 주소 |
| `<tagid>` | 복사한 광고 단위 ID |

## 광고 요청과 표시

### 광고 요청하기

빈 JSON 객체로 광고를 요청합니다.

```bash theme={null}
curl -X POST "https://your_a2_service/app/v0/ad/<tagid>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

광고가 선택되면 HTTP `200`과 광고 응답이 반환됩니다. 이미지 배너 응답에서 표시할 이미지와 랜딩 주소는 `ad.display.banner`, 이벤트에 사용할 광고 추적 식별자는 최상위 `ext.ad_log`에서 확인합니다.

```json Response (일부) theme={null}
{
  "ad": {
    "id": "7c4f2b18-e9a6-4d3f-b821-56a09c73e4fd",
    "display": {
      "w": 300,
      "h": 250,
      "banner": {
        "img": "https://cdn.example.com/banner.jpg",
        "link": {
          "url": "https://shop.example.com/products/1234"
        }
      }
    }
  },
  "ext": {
    "message": "success",
    "ad_log": "<A2가 반환한 광고 추적 식별자>"
  }
}
```

HTTP `204`는 반환할 광고가 없다는 정상 응답입니다. 응답 본문을 JSON으로 해석하지 말고 송출할 광고 설정을 확인하세요.

### 이미지 배너 표시하기

아래 예제는 광고를 새로 요청합니다. 앞선 curl 요청과 다른 광고가 반환될 수 있으며, 클릭 이벤트에는 **웹 화면에 표시된 광고**의 `ad_log`를 사용하세요.

다음 내용을 `quick-start.html`로 저장하고 `baseUrl`과 `tagid`를 바꿉니다.

```html theme={null}
<!doctype html>
<html lang="ko">
  <body>
    <div id="ad-slot">광고 요청 중</div>
    <p>ad_log: <code id="ad-log">아직 없음</code></p>

    <script>
      const baseUrl = "https://your_a2_service";
      const tagid = "<tagid>";
      const slot = document.querySelector("#ad-slot");
      const adLogView = document.querySelector("#ad-log");

      function showMessage(message) {
        slot.textContent = message;
        adLogView.textContent = "없음";
      }

      async function loadAd() {
        const result = await fetch(`${baseUrl}/app/v0/ad/${tagid}`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: "{}",
        });

        if (result.status === 204) {
          showMessage("반환된 광고가 없습니다.");
          return;
        }
        if (!result.ok) throw new Error(`광고 요청 실패: ${result.status}`);

        const response = await result.json();
        const display = response.ad?.display;
        const banner = display?.banner;
        const adLog = response.ext?.ad_log;
        if (!banner?.img) throw new Error("이미지 배너 응답이 아닙니다.");
        if (!banner.link?.url) throw new Error("랜딩 주소가 없습니다.");
        if (!adLog) throw new Error("ad_log가 없습니다.");

        const image = document.createElement("img");
        image.onload = () => {
          adLogView.textContent = adLog;
        };
        image.onerror = () => showMessage("이미지를 불러오지 못했습니다.");
        image.src = banner.img;
        image.alt = "Advertisement";
        if (display.w) image.width = display.w;
        if (display.h) image.height = display.h;

        const link = document.createElement("a");
        link.href = banner.link.url;
        link.target = "_blank";
        link.rel = "noopener";
        link.append(image);
        slot.replaceChildren(link);
      }

      loadAd().catch((error) => showMessage(error.message));
    </script>
  </body>
</html>
```

파일을 저장한 디렉터리에서 로컬 웹 서버를 실행한 뒤, 웹 브라우저에서 `http://localhost:8000/quick-start.html`을 엽니다.

```bash theme={null}
python3 -m http.server 8000
```

curl 요청은 성공하는데 화면에 요청 실패 메시지가 표시되면 [브라우저에서만 요청이 실패할 때](https://docs.aiderx.io/development/ko/integration-verification-and-troubleshooting.md#browser-request-failure)를 참고하세요.

`ad_log`는 배너 이미지가 표시된 경우에만 나타납니다. 광고가 없거나 요청·이미지 로딩에 실패하면 광고 영역에 표시된 메시지를 확인하고, 클릭 이벤트 전송 단계로 넘어가지 마세요.

이미지가 표시되면 배너를 한 번 클릭해 랜딩 페이지가 열리는지 확인한 뒤, 화면에 표시된 `ad_log`를 복사합니다.

## 클릭 이벤트 전송

`<ad_log>`를 웹 화면에서 복사한 `ad_log`로 바꿔 클릭 이벤트를 한 번 보냅니다.

```bash theme={null}
curl -i -X POST "https://your_a2_service/dmp/v0/log" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ad_log",
    "action": "clk",
    "ad_log": "<ad_log>"
  }'
```

응답에서 HTTP `200`을 확인한 뒤 실제 수집 여부를 다음 절에서 확인하세요.

## 결과 확인

Ad Manager의 **분석 > 광고 인벤토리 분석 > 광고 단위 분석**에서 실습에 사용한 광고 단위를 선택하고 조회 기간을 오늘로 설정합니다. 실습 전에 확인한 값보다 클릭 수가 1 늘었는지 확인하세요. 노출은 curl과 웹 페이지의 광고 요청 중 광고가 반환된 요청마다 기록되므로, 노출 수는 그 횟수만큼 늘어날 수 있습니다. 광고 없음 응답(HTTP `204`)을 받은 요청은 노출로 기록되지 않습니다.

기본 설정에서는 클릭 이벤트가 보통 1분 안에 집계에 반영됩니다. 1분 정도 지난 뒤 브라우저에서 페이지를 다시 불러와 확인하고, 확인을 위해 클릭 이벤트를 반복해서 전송하지 마세요. 다시 불러와도 반영되지 않으면 [이벤트 전송은 성공했는데 리포트에 반영되지 않을 때](https://docs.aiderx.io/development/ko/integration-verification-and-troubleshooting.md#event-not-reported)를 참고하세요.

| 확인 항목 | 완료 기준 |
| - | - |
| 광고 요청 | HTTP `200` 응답에 `ad`와 `ext.ad_log`가 있음 |
| 광고 표시 | 이미지 배너가 표시되고 클릭하면 랜딩 페이지가 열림 |
| 이벤트 전송 | 클릭 이벤트 요청이 HTTP `200`을 반환함 |
| 이벤트 수집 | 광고 단위의 클릭 수가 실습 전보다 1 증가함 |

## 다음 단계

**1. 서비스 구현 확장하기**

[광고 송출 연동](https://docs.aiderx.io/development/ko/serving-ad.md)과 [광고 이벤트·로그 연동](https://docs.aiderx.io/development/ko/ad-events-and-logs.md)에서 소재별 표시와 노출·클릭·전환 처리를 구현합니다.

**2. 완료 여부 확인하기**

[연동 검증과 문제 해결](https://docs.aiderx.io/development/ko/integration-verification-and-troubleshooting.md)의 검증표로 API 응답과 리포트 반영을 확인합니다.

인증이 필요한 API를 사용한다면 [API 접속과 인증](https://docs.aiderx.io/development/ko/api-access-and-auth.md)에서 액세스 토큰 발급과 보관 방법을 먼저 확인하세요.


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