> 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/tools/web-sdk/iaa.md).

# 04. In App Advertising (IAA)

### **Supported Ad Types**

The SDK supports two ad types.

<table><thead><tr><th width="160">Type</th><th width="300">API</th><th>Reward</th></tr></thead><tbody><tr><td>Rewarded ad</td><td><code>sdk.ads.showRewardedAsync()</code></td><td>In-game reward granted when viewing is completed</td></tr><tr><td>Interstitial ad</td><td><code>sdk.ads.showInterstitialAsync()</code></td><td>No reward (shown at natural breaks such as stage transitions)</td></tr></tbody></table>

{% hint style="warning" %}
**Required: Obtain an Ad Placement ID (placementId) in Advance**

To request ads, you must obtain an ad placement ID (placementId) in advance. Placement IDs are issued per game in the ONE store Developer Center (one each for rewarded and interstitial ads). A request with an unissued placement fails with no fallback. Please refer to [Monetization > In-app advertising](https://onestore-dev.gitbook.io/dev/eng/docs/apps/product/monetization/iaa) for the placement issuance procedure.
{% endhint %}

### **Checking Ad Feature Availability: isSupported**

<table><thead><tr><th width="300">Call</th><th width="100">Returns</th><th>Meaning</th></tr></thead><tbody><tr><td><code>sdk.ads.isSupported()</code></td><td>boolean</td><td>true if both rewarded and interstitial ads are supported</td></tr><tr><td><code>sdk.ads.isSupported("rewarded")</code></td><td>boolean</td><td>Whether rewarded ads are supported</td></tr><tr><td><code>sdk.ads.isSupported("interstitial")</code></td><td>boolean</td><td>Whether interstitial ads are supported</td></tr></tbody></table>

```javascript
// Check after initializeAsync(), and show the button only if supported
if (sdk.ads.isSupported("rewarded")) {
  showRewardButton();
}
```

* The result is determined from the initialization response, so call it **after** `initializeAsync()`. Before that, it may optimistically return true.
* This is a different concept from ad inventory (`isReadyAsync`). `isSupported` answers "does this app version provide this ad feature?", while `isReadyAsync` answers "is there an ad to show right now?".
* If you request an ad while unsupported, `{ status: "failed", reason: "platform_not_supported" }` is returned without calling the app.

### **Requesting Ads: showRewardedAsync / showInterstitialAsync**

Both APIs take their parameters as a JSON object.

```javascript
// Rewarded ad
async function showRewardedAd() {
  var requestId = await issueRequestIdFromMyServer();   // Issuing from the game server is recommended

  var result = await sdk.ads.showRewardedAsync({
    placementId: "REWARD_PLACEMENT_ID",
    requestId: requestId
  });

  if (result.status === "rewarded") {
    // This is only an ad-shown signal — grant the reward after confirming the postback (SSV) on your server
    playRewardEffect();
    await checkRewardOnMyServer(result.requestId);
    return;
  }

  if (result.status === "dismissed") {
    showToast("You must watch the ad to the end to receive the reward.");
    return;
  }

  // status === "failed" — not eligible for a reward (including no_fill)
  if (result.reason === "no_fill") {
    showToast("No ad is available right now.");
  }
  continueWithoutAd();               // Alternative path to continue without an ad
}

// Interstitial ad
async function showInterstitialAd() {
  var r = await sdk.ads.showInterstitialAsync({
    placementId: "INTERSTITIAL_PLACEMENT_ID"
  });
  // r.status is "completed" or "failed" — either way, the game continues
  goToNextStage();
}
```

**Request Parameters**

<table><thead><tr><th width="130">Parameter</th><th width="80">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td>placementId</td><td>string</td><td>Required</td><td>The ad placement ID obtained in advance. If omitted, <code>{ status: "failed", reason: "invalid_request" }</code> is returned immediately without calling the app</td></tr><tr><td>requestId</td><td>string</td><td>Required for rewarded ads</td><td>Tracking key for reward granting. This is a <strong>required value</strong>. To identify which user a reward belongs to when the postback is received, we <strong>recommend</strong> that the game server issue it and map it to the user. The SDK does not generate this value automatically, so the game must pass it. If omitted, <code>{ status: "failed", reason: "invalid_request" }</code> is returned immediately without calling the app. Not used for interstitial ads</td></tr><tr><td>timeoutMs</td><td>number</td><td>Optional</td><td>Maximum wait (ms) for the ad result. Applies <strong>until the ad-closed response</strong>. Default 600000 (10 minutes), allowed range 1000 to 1800000 (30 minutes). Values outside the range are replaced with the default (600000). The default comfortably covers long-format ads such as playable ads, so you normally do not need to set it</td></tr></tbody></table>

**Return Value (AdResult)**

The ad APIs do not reject on failure. They resolve with the object below.

<table><thead><tr><th width="120">Field</th><th width="200">Present When</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>Always</td><td>Rewarded: <code>"rewarded"</code> (viewing completed) / <code>"dismissed"</code> (left early) / <code>"failed"</code> · Interstitial: <code>"completed"</code> / <code>"failed"</code></td></tr><tr><td>requestId</td><td>Rewarded ads</td><td>Returns the tracking key passed in the request as is. <strong>Returned even on failure or timeout</strong>, so it can be used to match requests. Not present in interstitial ad results</td></tr><tr><td>reason</td><td>When status is <code>"failed"</code></td><td>Failure reason string (e.g. <code>"no_fill"</code>). See <a href="https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/errors.md">06. Error Reasons (reason)</a>. Use it as the branching condition</td></tr></tbody></table>

{% hint style="danger" %}
**Reward Granting Principles**

* `status: "rewarded"` is **only an ad-shown signal, not grounds for granting a reward.** The actual reward is confirmed through a postback (SSV) delivered to the game server after verification by the ad server. The game must query its own server for the grant status and then apply it.

* Therefore, the `requestId` of a rewarded ad must be issued by the game developer so that the user who owns the reward can be identified when the postback is received.

* Play the reward effect only when `status` is `"rewarded"`. `"dismissed"` (left early) and `"failed"` are not eligible for a reward. In particular, **no reward is granted when the ad could not be shown due to lack of inventory (`reason: "no_fill"`).** Instead of granting a reward, provide an alternative path so the game does not get stuck.
  {% endhint %}

* Failures are returned as `{ status: "failed", reason }`, not thrown as exceptions. Ads can fail at any time, for example due to lack of inventory (no\_fill), so handle them so that the game does not get stuck.

* `pause` / `resume` events are delivered while an ad is displayed (see [03. Lifecycle Management](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/lifecycle.md)). The game only needs to handle them in one pause listener.

* Only one ad or payment screen is displayed at a time. An additional ad request while one is displayed returns `{ status: "failed", reason: "already_showing" }` immediately.

* An ad may still be shown late after a `timeout` failure. Avoid immediately re-requesting the same placement, and use the returned `requestId` to guard against duplicate rewards.

### **Ad Preloading and Inventory Check (Optional)**

To reduce response time at the moment of display, you can request loading ahead of display.

```javascript
// Preloading — only accepted; completion is not reported back
sdk.ads.loadRewarded({ placementId: "REWARD_PLACEMENT_ID" });
sdk.ads.loadInterstitial({ placementId: "INTERSTITIAL_PLACEMENT_ID" });

// Inventory check — pass both arguments
var ready = await sdk.ads.isReadyAsync("rewarded", "REWARD_PLACEMENT_ID");
```

<table><thead><tr><th width="260">API</th><th>Parameters</th><th width="180">Returns</th></tr></thead><tbody><tr><td><code>sdk.ads.loadRewarded(options)</code><br><code>sdk.ads.loadInterstitial(options)</code></td><td><code>options.placementId</code> (string, required)</td><td>None (one-way request)</td></tr><tr><td><code>sdk.ads.isReadyAsync(type, placementId)</code></td><td><code>type</code>: <code>"rewarded"</code> or <code>"interstitial"</code> (required)<br><code>placementId</code>: placement ID to check (required). If omitted, false is returned without asking the app</td><td><code>Promise&#x3C;boolean></code></td></tr></tbody></table>

* Preloading is optional. Even if you do not call it, loading happens internally when display is requested (though the wait until the first display may be longer).
* Preloading is only accepted; completion is not reported back. Repeated calls for the same placement do not cause duplicate loads. If `placementId` is omitted, the request itself is ignored.
* `isReadyAsync` resolves with a boolean. The result is **for reference only**. Even if true, the display may fail depending on inventory at display time. An unregistered placement, a placement type mismatch, a lookup failure, a missing `placementId`, and a user who has opted out of ads all return false (no error is thrown).
