> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/docs/apps/product/monetization/iaa.md).

# 인앱 광고 (IAA)

## **인앱 광고(IAA) 란?**

인앱 광고는 Web 게임 내에 별도의 결제 없이 광고 노출을 통해 부가 수익을 만들 수 있는 수익화 기능입니다. 

{% hint style="info" %}
인앱 광고는 Web 상품인 경우에만 제공됩니다.
{% endhint %}

## 인앱 광고 설정 단계

인앱 광고는 아래와 같은 단계로 설정하실 수 있습니다.

{% stepper %}
{% step %}

#### 인앱 광고 사용 설정

\[APPS > 상품현황 > Web 상품관리> 기본정보 > 광고 적용 여부] 메뉴에서  광고 적용 여부를 "**예**"로 체크해 주세요.
{% endstep %}

{% step %}

#### 광고 ID(Placement ID) 발급

\[APPS > 상품현황 > 수익화 > 인앱 광고] 메뉴에서 광고 ID를 발급해 주세요.
{% endstep %}

{% step %}

#### Web SDK 연동

발급받은 광고 ID와 Web SDK를 연동해 주세요.
{% endstep %}

{% step %}

#### 콜백 서버 URL / API Key 연동 

리워드 비디오 광고인 경우 콜백 URL 과 API Key 정보를 등록해 주세요.
{% endstep %}
{% endstepper %}

각 단계의 자세한 내용은 아래의 각 섹션에서 확인해 주세요.

***

## 광고 ID(Placement ID) 발급

\[APPS > 상품현황 > 수익화 > 인앱 광고] 화면에서 광고 타입 별로 **\[ID 발급 요청]** 버튼을 눌러 광고 ID(Placement ID) 발급을 요청합니다.

{% hint style="info" %}

* 광고 ID(Placement ID)는 타입 별 **1개**씩 발급 가능합니다
* 발급 요청 후 발급까지는 영업일 기준 **평균 1일**이 소요됩니다.
  {% endhint %}

### 지원하는 광고 타입

<table><thead><tr><th width="183">광고 타입</th><th>설명</th></tr></thead><tbody><tr><td><strong>전면 광고</strong></td><td>화면 전환 시점 등에 전체 화면으로 노출되는 광고</td></tr><tr><td><strong>리워드 비디오 광고</strong></td><td>동영상 시청을 완료한 사용자에게 보상을 제공하는 광고</td></tr></tbody></table>

#### 광고 ID 발급 상태

<table><thead><tr><th width="144">상태</th><th>설명</th></tr></thead><tbody><tr><td><strong>미발급</strong></td><td><p>광고 ID를 아직 발급받지 않은 상태</p><ul><li>화면에 <strong>[ID 발급 요청]</strong> 버튼이 활성화됩니다.</li></ul></td></tr><tr><td><strong>발급 처리중</strong></td><td><p>발급 요청이 접수되어 처리 중인 상태</p><ul><li>화면에 <strong>[발급 처리중]</strong> 문구가 표시됩니다.</li></ul></td></tr><tr><td><strong>발급 완료</strong></td><td><p>광고 ID(상용 ID)가 발급되어 바로 사용할 수 있는 상태</p><ul><li>발급이 완료되면 화면에 <strong>상용 광고 ID</strong>가 표시됩니다.</li></ul></td></tr><tr><td><strong>발급 실패</strong></td><td><p>발급에 실패한 상태 </p><ul><li> <strong>[다시 시도]</strong> 버튼으로 재요청이 가능하며, 지속적으로 발급이 실패할 경우 메일로 문의해 주세요.</li><li>문의 이메일 :  <a href="mailto:devhelper@onestore.net">devhelper@onestore.net</a></li></ul></td></tr></tbody></table>

{% hint style="info" %}
**안내**

* 리워드 비디오 광고의 경우 광고ID가 **발급 완료** 상태가 되면 콜백 서버 등록과 API Key 등록 영역이 활성화됩니다.&#x20;
* 전면 광고만 사용하는 경우에는 콜백 URL을 등록하지 않아도 됩니다.
* 테스트 광고 ID는 제공되지 않으며, 필요한 경우 문의해 주시기 바랍니다.
  {% endhint %}

***

## Web SDK 연동

Web SDK 연동 가이드는 아래의 페이지에서 확인해 주세요.

{% content-ref url="/pages/9c4f5df51c9881725a96f7be14d0b91027b31c2e" %}
[04. 인앱 광고 (IAA)](/dev/tools/web-sdk/iaa.md)
{% endcontent-ref %}

***

## 콜백 서버 URL 연동

리워드 비디오 광고 시청 완료 후, 보상 지급을 위해서는 개발사 서버로 전달되는 콜백 서버(SSV- Server-to-Server Verification) URL 등록이 필요합니다.

### 콜백 서버URL / API Key 등록

콜백 URL과 API Key는 **\[APPS > 상품현황 > 수익화 > 인앱 광고]** 화면에서 등록합니다.

<table><thead><tr><th width="165">항목</th><th>설명</th></tr></thead><tbody><tr><td><strong>콜백 서버 (상용)</strong></td><td>실서비스 환경에서 SSV 콜백을 받을 서버 주소 </td></tr><tr><td><strong>API Key</strong></td><td><p>콜백 API 호출 시 개발사 서버에서 요청을 인증하기 위해 사용하는 인증 정보</p><ul><li> 허용 문자 A-Z, a-z, 0-9, -, _ / 길이 5~64자</li></ul></td></tr></tbody></table>

### 1. Request URL

<table><thead><tr><th width="177">항목</th><th>값</th></tr></thead><tbody><tr><td><strong>URI</strong></td><td>개발사가 사전에 등록한 콜백 URL</td></tr><tr><td><strong>Protocol</strong></td><td>HTTPS</td></tr><tr><td><strong>Method</strong></td><td>POST</td></tr><tr><td><strong>Accept</strong></td><td><code>application/json</code></td></tr><tr><td><strong>Content-Type</strong></td><td><code>application/json</code></td></tr><tr><td><strong>인증</strong></td><td>고정 헤더(<code>x-API-KEY</code>) + HMAC-SHA256 서명(<code>x-TIMESTAMP</code> · <code>x-SIGNATURE</code>)</td></tr></tbody></table>

### 2. Request Header

<table><thead><tr><th width="136">Name</th><th width="133">Necessity</th><th>Description</th></tr></thead><tbody><tr><td><code>x-API-KEY</code></td><td>Required</td><td><p>개발사가 발급한 콜백 인증키를 고정 문자열 그대로 싣습니다. </p><p>(콜백 URL / API Key 등록 메뉴에서 등록한 API Key)</p></td></tr><tr><td><code>x-TIMESTAMP</code></td><td>Required</td><td><p>발신 시각(epoch millis)입니다.</p><p>짧은 유효창(예: ±5분) 안의 값만 인정해야 합니다 </p><ul><li>과거 요청의 재전송(리플레이)을 막기 위함</li></ul></td></tr><tr><td><code>x-SIGNATURE</code></td><td>Required</td><td><p>HMAC-SHA256(hex)입니다. </p><ul><li>서명 대상은 3.1  서명  대상 섹션을 참고해 주세요.</li></ul></td></tr></tbody></table>

### 3. Request Format (Body)

<table><thead><tr><th width="177">Name</th><th width="101">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>requestId</code></td><td>String</td><td>요청 시 개발사가 보낸 값 그대로</td></tr><tr><td><code>status</code></td><td>String</td><td><code>SUCCESS</code> 고정</td></tr><tr><td><code>reason</code></td><td>String</td><td>빈 문자열(<code>""</code>) 고정</td></tr></tbody></table>

#### **3.1 서명 대상 (canonical string)**

`x-SIGNATURE` 대상 문자열은 `x-TIMESTAMP`와 실제 전송한 body 바이트 그대로를 개행으로 잇습니다.

```
timestamp + "\n" + rawBody
```

* body를 필드별로 다시 뽑아 조립하지 않습니다&#x20;
  * &#x20;수신한 body 바이트를 그대로 서명 대상에 이어붙여야 합니다.&#x20;
  * 필드 순서·공백·이스케이프를 다시 파싱·직렬화하면 원본과 다른 문자열이 만들어질 수 있습니다.
* 키(비밀키)는 발급받은 인증키(`x-API-KEY` 값)를 그대로 사용합니다.

### **Request Example**

```
POST /onestore/reward-ad/webhook HTTP/1.1
Host: game.example.com
Content-Type: application/json
x-API-KEY: a16774f019d1e251c214a38946331ec6
x-TIMESTAMP: 1700000000000
x-SIGNATURE: 3b1c9e5f7a2d4c6b8e0f1a3d5c7b9e2f4a6c8d0e1b3f5a7c9d0e2f4a6b8c0d1e
 
{"requestId":"dev-tx-88214","status":"SUCCESS","reason":""}
```

* 예시의 `x-SIGNATURE` 는 `HMAC-SHA256(인증키, "1700000000000\n{"requestId":"dev-tx-88214","status":"SUCCESS","reason":""}")` 입니다.
* body 는 들여쓰지 않고 **실제 전송된 한 줄 그대로**여야만 서명이 일치합니다.

### 4. Response Format

<table><thead><tr><th width="161">판정</th><th>조건</th></tr></thead><tbody><tr><td><strong>성공</strong></td><td>2xx</td></tr><tr><td><strong>실패</strong></td><td>그 외(4xx·5xx·타임아웃)</td></tr></tbody></table>

* 응답 바디는 파싱하지 않습니다.

***

## 광고 통계

서비스하고 있는 인앱 광고의 성과를 대시보드로 확인할 수 있습니다.

<table><thead><tr><th width="164">항목</th><th>내용</th></tr></thead><tbody><tr><td>데이터 집계</td><td>전일자 데이터는 매일 오후 중 집계 완료됩니다.</td></tr><tr><td>예상 수익</td><td>표시된 금액은 예상 수익이며, 익월 초 확정됩니다.</td></tr></tbody></table>

***