> 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/eng/docs/apps/product/monetization/iaa.md).

# In-App Advertising (IAA)

## What is In-App Ads **(IAA) ?**

In-App Advertising is a monetization feature that generates additional revenue from ad impressions in a Web game, without requiring in-app purchases.

{% hint style="info" %}
In-App Ads is available only for Web products.
{% endhint %}

## In-App Ads Setup Steps

In-App Advertising can be set up using the following steps.

{% stepper %}
{% step %}

#### Enable In-App Ads

In the \[Apps > Applications > Web App Mgmt. > Main Info > Ad Application] menu, set **Ad Application** to "Yes."
{% endstep %}

{% step %}

#### Create an ad ID (Placement ID)

In the \[APPS > Applications > Monetization >In-App Ads] menu, create an Ad ID.
{% endstep %}

{% step %}

#### Integrate the Web SDK

Integrate the Web SDK using your Ad ID.
{% endstep %}

{% step %}

#### Register the Callback Server URL / API Key

For Rewarded Video Ads, register a Callback URL and an API Key.
{% endstep %}

{% step %}

#### Confirm that Ad Application is set to "Yes"

Please check the value set for \[Ad Application] in Step 1. \
If Ad Application is set to "No," ads will not be served correctly, so make sure to set it to **"Yes."**
{% endstep %}
{% endstepper %}

For details on each step, see the sections below.

***

## Ad ID (Placement ID) Creation

On the \[APPS > Applications > Monetization >In-App Ads] screen, click **\[Create ID]** for each ad type to request an Ad ID (Placement ID).

{% hint style="info" %}

* One Ad ID (Placement ID) can be created per ad type.
* It typically takes about **one business day** from request to creation.
  {% endhint %}

### Supported Ad Types

<table><thead><tr><th width="217">Ad Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Interstitial Ad</strong></td><td>A full-screen ad displayed at natural transition points, such as between screens.</td></tr><tr><td><strong>Rewarded Video Ad</strong></td><td>A video ad that rewards users who finish watching it.</td></tr></tbody></table>

#### Ad ID (Placement ID) Creation Status

<table><thead><tr><th width="144">Status</th><th>Description</th></tr></thead><tbody><tr><td><strong>Not Created</strong></td><td><p>The Ad ID has not yet been created. </p><ul><li>The <strong>[Create ID]</strong> button is active on the screen.</li></ul></td></tr><tr><td><strong>Pending</strong></td><td><p>The creation request has been received and is being processed. </p><ul><li><strong>[Pending]</strong> is displayed on the screen.</li></ul></td></tr><tr><td><strong>Created</strong></td><td><p>The Ad ID (Production ID) has been created and is ready to use. </p><ul><li>Once created, the <strong>Production Ad ID</strong> is displayed on the screen.</li></ul></td></tr><tr><td><strong>Creation Failed</strong></td><td><p>Creation has failed. </p><ul><li>Click <strong>[Retry]</strong> to request again. If creation continues to fail, please contact us by email.</li><li>Contact email: <a href="mailto:devhelper@onestore.net">devhelper@onestore.net</a></li></ul></td></tr></tbody></table>

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

* For Rewarded Video Ads, the Callback Server and API Key registration fields are activated once the Ad ID status becomes **Created**.
* If only Interstitial Ads are used, registering a Callback URL is not required.
* Test ads are not supported.
  {% endhint %}

***

## Web SDK Integration

For the Web SDK integration guide, see the page below.

{% content-ref url="/pages/d6ea3528547ac93c13c21aa4552dfe63ac79aded" %}
[04. In App Advertising (IAA)](/dev/eng/tools/web-sdk/iaa.md)
{% endcontent-ref %}

***

## Callback Server URL Integration

After a user completes watching a Rewarded Video Ad, a Callback Server (SSV, Server-to-Server Verification) URL must be registered to deliver the reward-payout request to the developer's server.

### Callback Server URL / API Key Registration

The Callback URL and API Key are registered on the\[APPS > Applications > Monetization >In-App Ads] screen.

<table><thead><tr><th width="165">Item</th><th>Description</th></tr></thead><tbody><tr><td><strong>Callback Server (Production)</strong></td><td>The server address that receives SSV callbacks in the production environment. </td></tr><tr><td><strong>API Key</strong></td><td><p>Authentication information used to verify requests from the developer's server when calling the callback API.</p><ul><li> Allowed characters: A-Z, a-z, 0-9, -, _ / Length: 5–64 characters</li></ul></td></tr></tbody></table>

### 1. Request URL

<table><thead><tr><th width="177">Item</th><th>Value</th></tr></thead><tbody><tr><td><strong>URI</strong></td><td>The Callback URL pre-registered by the developer</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>Authentication</strong></td><td>Fixed header(<code>x-API-KEY</code>) + HMAC-SHA256 signature(<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>he callback authentication key issued by the developer, sent as a fixed string without modification. </p><p>(The API Key registered under "Callback Server URL / API Key Registration.")</p></td></tr><tr><td><code>x-TIMESTAMP</code></td><td>Required</td><td><p>The time the request was sent (epoch milliseconds).</p><ul><li>Only values within a short validity window (e.g., ±5 minutes) should be accepted, to prevent replay of past requests.</li></ul></td></tr><tr><td><code>x-SIGNATURE</code></td><td>Required</td><td><p>An HMAC-SHA256 signature (hex). </p><ul><li>See section 3.1 for the signing target.</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>The value originally sent by the developer, returned as-is</td></tr><tr><td><code>status</code></td><td>String</td><td>Fixed as <code>SUCCESS</code></td></tr><tr><td><code>reason</code></td><td>String</td><td>Fixed as an empty string (<code>""</code>)</td></tr></tbody></table>

#### **3.1** Signing Target (canonical string)

The `x-SIGNATURE` signing target string joins `x-TIMESTAMP` and the exact bytes of the transmitted body with a newline.

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

* Do not reconstruct the body field by field&#x20;
  * the received body bytes must be appended to the signing target exactly as received.&#x20;
  * Re-parsing and re-serializing the fields (which can change field order, whitespace, or escaping) may produce a string different from the original.
* The secret key is the issued authentication key (the `x-API-KEY` value), used as-is.

### **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":""}
```

* In this example, `x-SIGNATURE` is `HMAC-SHA256(API key, "1700000000000\n{"requestId":"dev-tx-88214","status":"SUCCESS","reason":""}")`.
* For the signature to match, the body must be a single line, unindented, exactly as transmitted.

### 4. Response Format

<table><thead><tr><th width="161">Result</th><th>Condition</th></tr></thead><tbody><tr><td><strong>Success</strong></td><td>2xx</td></tr><tr><td><strong>Fail</strong></td><td>Any other response (4xx, 5xx, timeout)</td></tr></tbody></table>

* The response body is not parsed.

***

## Ad Statistics

In-App Advertising performance data is available on the dashboard.

<table><thead><tr><th width="164">Item</th><th>Description</th></tr></thead><tbody><tr><td>Data Aggregation</td><td>Data for the previous day is aggregated during the afternoon each day.</td></tr><tr><td>Estimated Revenue</td><td>The amount shown is estimated revenue. Final amounts are confirmed at the beginning of the following month.</td></tr></tbody></table>

***