# Ads API

Monetize your game with rewarded videos and interstitials. The host manages presentation; your game just requests placements and reacts to the result.

{% hint style="warning" %}
All SDK methods can reject — unhandled rejections crash the app. Always wrap SDK calls in `try/catch` or attach a `.catch()` handler. See [Error Handling](/rundot-docs/v5.15.0/readme/error-handling.md) for details.
{% endhint %}

{% hint style="danger" %}
Ads are not currently supported on Desktop.\
Calling the Ads API on Desktop will show a universal link to the mobile app.
{% endhint %}

## Ad Types

### Rewarded Video Ads

Opt-in ads where players receive rewards for watching. Players choose to watch these ads in exchange for in-game benefits.

```typescript
const isReady = await RundotGameAPI.ads.isRewardedAdReadyAsync()
if (isReady) {
  const rewarded = await RundotGameAPI.ads.showRewardedAdAsync()
  if (rewarded) {
    grantReward() // Player watched the full ad
  }
}
```

**Use cases:**

* Extra lives or continues
* Bonus currency
* Speed up timers
* Unlock temporary power-ups

### Interstitial Ads

Forced ads that interrupt gameplay at natural break points. These ads are automatically hidden for platform subscribers.

```typescript
const isReady = await RundotGameAPI.ads.isInterstitialAdReadyAsync()
if (isReady) {
  // Show interstitial at level transition
  await RundotGameAPI.ads.showInterstitialAd()
  // Gameplay resumes after ad completes or is skipped
}
```

**Use cases:**

* Between levels
* After game over
* After completing a session
* On menu transitions

> **Note**: Interstitial ads are hidden for users with platform subscriptions. Your code can safely call `showInterstitialAd()` for all users—subscribers simply won't see the ad.

## Quick Start

```typescript
import RundotGameAPI from '@series-inc/rundot-game-sdk/api'

const isReady = await RundotGameAPI.ads.isRewardedAdReadyAsync()
if (isReady) {
  const rewarded = await RundotGameAPI.ads.showRewardedAdAsync()
  if (rewarded) {
    grantReward()
  }
}
```

## Complete Example

```typescript
// Rewarded ad button handler
async function onWatchAdForReward() {
  const isReady = await RundotGameAPI.ads.isRewardedAdReadyAsync()
  
  if (!isReady) {
    showMessage('No ad available right now')
    return
  }
  
  try {
    const watched = await RundotGameAPI.ads.showRewardedAdAsync()
    if (watched) {
      grantBonus(100) // Give the reward
      await RundotGameAPI.analytics.recordCustomEvent('rewarded_ad_complete', {
        reward: 'bonus_100',
      })
    }
  } catch (error) {
    console.error('Ad failed:', error)
  }
}

// Interstitial between levels
async function onLevelComplete(level: number) {
  saveProgress(level)
  
  // Show interstitial every 3 levels
  if (level % 3 === 0) {
    await RundotGameAPI.ads.showInterstitialAd()
  }
  
  loadNextLevel(level + 1)
}
```

## API Reference

| Method                          | Returns            | Description                                 |
| ------------------------------- | ------------------ | ------------------------------------------- |
| `isRewardedAdReadyAsync()`      | `Promise<boolean>` | Check if a rewarded ad is available         |
| `isInterstitialAdReadyAsync()`  | `Promise<boolean>` | Check if an interstitial ad is available    |
| `showRewardedAdAsync(options?)` | `Promise<boolean>` | Show rewarded ad; returns `true` if watched |
| `showInterstitialAd(options?)`  | `Promise<boolean>` | Show interstitial ad                        |

## Best Practices

* Preflight with `isRewardedAdReadyAsync()` / `isInterstitialAdReadyAsync()` before calling display methods—hosts may throttle requests during campaigns.
* Disable reward buttons when `isRewardedAdReadyAsync()` returns `false` to avoid extra clicks.
* Guard reward logic so you only grant the prize when the call resolves `true`.
* Wrap ad calls in try/catch and fail silently; players might deny permissions or lose connectivity.
* Show interstitials at natural break points (level transitions, game over) not mid-gameplay.
* Don't show interstitials too frequently—player experience matters.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://series-1.gitbook.io/rundot-docs/v5.15.0/readme/ads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.