> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/natively-platform/features/admob.md).

# AdMob

## What is AdMob?

Natively provides built-in support for [Google AdMob](https://admob.google.com/) to help you monetize your iOS and Android app through banner and interstitial ads. AdMob manages ad inventory, targeting, and delivery through its own console, and Natively handles displaying ads within your app.

{% hint style="warning" %}
Currently, Natively only supports **Banner** and **Interstitial** ad formats.
{% endhint %}

## Prerequisites

{% hint style="success" %}
This feature requires the **Unlimited** or **Lifetime** plan. [See all plans](/getting-started/subscription-plans.md)
{% endhint %}

* A [Google AdMob](https://admob.google.com/) account.
* Your iOS and/or Android app [published](/natively-platform/app-info.md) in the Natively Dashboard.

## Google AdMob Configuration

### AdMob App configuration

{% stepper %}
{% step %}

#### Create app in AdMob

1. Log in to your [Google AdMob Console](https://admob.google.com/).
2. Navigate to **Apps** and click **Add Your First App** (or **Add App** if you already have other apps).
3. Select the platform - iOS or Android.
4. Indicate whether the app is already listed on a supported app store:
   * **Yes** - search for your app and click **Add**.
   * **No** - select **No**, enter your app name, and click **Add App**.

{% hint style="info" %}
If you're building for both platforms, repeat this process to create two separate apps in AdMob - one per platform.
{% endhint %}

<div><figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FbghTM56fRnog5GP5VizP%252F1.png%3Falt%3Dmedia%26token%3D12006427-c50d-47cd-a92f-12691e0adb87&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=efd0417e&#x26;sv=2" alt=""><figcaption><p>Step 1-2</p></figcaption></figure> <figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FFn1vu5cdBZEzUBh7rQ4z%252F2.png%3Falt%3Dmedia%26token%3D974e9819-acc6-41d7-ae08-b1443dcbf3bb&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=4cc18175&#x26;sv=2" alt=""><figcaption><p>Step 3-4</p></figcaption></figure> <figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FfCZ7rEfHsdu26KXqdQkW%252F3.png%3Falt%3Dmedia%26token%3D35263e8b-4701-40f2-9a67-d9737093a603&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=358fe58e&#x26;sv=2" alt=""><figcaption><p>Step 4 - Yes</p></figcaption></figure> <figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252F971PF2yUTe2LLwda6wYJ%252F3-1.png%3Falt%3Dmedia%26token%3Dcf1c7836-e896-493e-94bd-595a322563c4&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=7680e7aa&#x26;sv=2" alt=""><figcaption><p>Step 4 - No</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### Retrieve AdMob app ID

1. Go to **Apps** > **View All Apps**.
2. Locate your newly created app.
3. Copy the **App ID** - it starts with `ca-app...` .

<figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FN5UUXc2kAcBXfHr9DcxK%252F5.png%3Falt%3Dmedia%26token%3D3b76dd72-0439-4f6b-a4f0-8cba4c834481&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=9af11d44&#x26;sv=2" alt="" width="188"><figcaption><p>AdMob app ID</p></figcaption></figure>
{% endstep %}
{% endstepper %}

For AdMob's full setup walkthrough, see [Google's AdMob setup guide](https://support.google.com/admob/answer/9989980?hl=en).

### AdMob Ad Units configuration

For each ad format you plan to use - Banner and/or Interstitial - create a corresponding Ad Unit in AdMob.

1. Go to **Apps** > \[your app] > **Ad units**.
2. Click **Add ad unit**.
3. Select the ad format (**Banner** or **Interstitial**).
4. Name the ad unit and click **Create ad unit**.
5. Copy the generated **Ad unit ID**.

{% hint style="info" %}
Repeat for each format and platform you support. You'll use these **Ad Unit IDs** later - for **testing** on a registered device and for your **production** build once you're ready to release.
{% endhint %}

## Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to **Features** > **AdMob**.
2. Toggle the feature to **Enabled**.
3. Paste the **App IDs** you copied from AdMob into the respective fields:
   * **iOS App ID**
   * **Android App ID**
4. *(iOS only)* Enter a **Permission Description**.
5. Click **Save**.
6. Rebuild your app(s).

{% hint style="info" %}
The **Permission Description** is the text shown to iOS users when the OS asks them to grant tracking permission (App Tracking Transparency). Explain clearly why your app needs this permission - for example: "We use your data to provide personalized advertisements that are relevant to your interests." A vague description may result in App Store rejection.
{% endhint %}

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

## Implementation

Choose your integration method below: **Bubble.io Plugin** (No-Code), **JavaScript SDK** (Code), or **AI Agents** (for AI-powered editors like Lovable, Base44, and Replit).

### Initialization

{% tabs %}
{% tab title="Bubble.io Plugin" %}
**Check Plugin**

Before starting, verify if the Natively plugin is already installed in your Bubble project.

1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
2. **Check Installed Plugins:** Look through your list of installed plugins for "Natively iOS & Android app builder".
   * If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

<figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FmfnSUug82IdnxOAoBrak%252Fnatively_app_builder_bubble_plugin_update.png%3Falt%3Dmedia%26token%3Dc193f69f-b03b-4be4-b80b-f34ba37ac212&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=a89e4510&#x26;sv=2" alt=""><figcaption></figcaption></figure>

* If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.

<figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FC5rA42yQHcN1uGKFbzmF%252Fnatively_app_builder_bubble_plugin.png%3Falt%3Dmedia%26token%3Dd9706d9b-dbe8-459b-b9b3-5667648aa4b7&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=9aae2297&#x26;sv=2" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="JavaScript SDK" %}
**Check SDK**

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

1. Open your project's main HTML file (or header settings) and look for the Natively script tag inside the `<head>` section.
2. Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., `@2.26.0`).

```javascript
<head>
  <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script>
</head>
```

{% hint style="info" %}
To ensure you are using the most up-to-date version, check the [Natively GitHub releases page](https://github.com/buildnatively/js-sdk/releases) for the latest version number.
{% endhint %}
{% endtab %}

{% tab title="AI Agents" %}
**Initialize the SDK**

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project.

Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project.

```
Check if the following Natively SDK script is present in the <head> of index.html. If missing or outdated, add it: <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script><script>function nativelyOnLoad() { window.natively.setDebug(true); console.log("✅ Natively SDK loaded successfully."); }</script> For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases
```

{% endtab %}
{% endtabs %}

### Setup Logic (**Banner Ads**)

{% tabs %}
{% tab title="Bubble.io Plugin" %}

### \[Element] Natively - Admob Banner

{% hint style="warning" %}
This element must be set to **Visible on page load** to initialize correctly. Place it directly on the page root - not inside Popups, Floating Groups, Group Focus elements, or Repeating Groups. To hide it from your UI, set its dimensions to 0x0 px.
{% endhint %}

#### Fields:

* **iOS UnitId** - your ad unit ID, or Google's test ad unit ID (`ca-app-pub-3940256099942544/2934735716`).
* **Android UnitId** - your ad unit ID, or Google's test ad unit ID (`ca-app-pub-3940256099942544/6300978111`).
* **Position** - `TOP` or `BOTTOM`.
* **Size Type** - `AUTO` or `CUSTOM`.
* **Banner Width** - applied only when **Size Type** is `CUSTOM`.
* **Banner Height** - applied only when **Size Type** is `CUSTOM`.
* **Preload Ad on Initialize** - loads the ad automatically on page load.
* **Show Ad on Initialize** - displays the ad automatically once loaded.

{% hint style="warning" %}
**Show Ad on Initialize** only takes effect if **Preload Ad on Initialize** is also enabled - showing an ad requires it to have loaded first. If preload is off, the ad will never auto-show, regardless of this setting.
{% endhint %}

#### Events:

* **Did finish setup** - fires when the banner has finished setting up and is ready to load an ad.
* **Did load ad** - fires when ad loading is finished, and the banner is ready to be displayed (called after **Load Ad** action).
* **Did fail to receive ad** - fires when loading the ad failed (can occur after **Load Ad** action).
* **Did record click** - fires when the user clicks on the banner.
* **Did record impression** - fires when the user sees the ad.
* **Did show banner** - fires when the banner is successfully shown.
* **Did hide banner** - fires when the banner is successfully hidden.

#### States:

* **Banner Is Ready** - Yes/No. Whether the banner has an ad ready to display.
* **Banner Is Visible** - Yes/No. Whether the banner is currently shown.
* **Ad Is Loaded** - Yes/No. Whether ad loading has finished.
* **Latest Error Message** - text description of the last error.
* **Latest Event** - the latest event code received from the app:
  * `DID_FINISH_SETUP` - the banner finished setting up and is ready to load an ad.
  * `DID_LOAD_AD` - ad loading finished, and the banner is ready to be displayed.
  * `DID_FAIL_TO_RECEIVE_AD` - loading the ad failed.
  * `DID_RECORD_CLICK` - the user clicked on the banner.
  * `DID_RECORD_IMPRESSION` - the user saw the ad.
  * `DID_SHOW_BANNER` - the banner was successfully shown.
  * `DID_HIDE_BANNER` - the banner was successfully hidden.

#### Actions:

* **Show Banner** - displays the banner on the screen.
* **Hide Banner** - removes the banner from the screen.
* **Load Ad** - manually fetches a new ad.
* **Check Banner Visible** - refreshes the **Banner Is Visible** state.
* **Check Banner Ready** - refreshes the **Banner Is Ready** state
  {% endtab %}

{% tab title="JavaScript SDK" %}

```javascript
// ============================================================================
// NATIVELY ADMOB BANNER - DOCUMENTATION & EXAMPLES
// ============================================================================

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// new NativelyAdmobBanner(config, setupCallback, preloadAd, preloadCallback, showAd, showCallback)
//   - Initializes and sets up the banner.
//   - config.androidUnitId / config.iOSUnitId: string — defaults to Google's test IDs if omitted.
//   - config.position: string — "TOP" or "BOTTOM". Default "BOTTOM".
//   - config.sizeType: string — "AUTO" or "CUSTOM". Default "AUTO".
//   - config.custom_width / config.custom_height: number — used only if sizeType is "CUSTOM".
//   - preloadAd: boolean — automatically loads an ad after setup. Default false.
//   - showAd: boolean — automatically shows the ad after a successful load.
//     Only takes effect if preloadAd is also true. Default false.
//
// banner.loadAd(callback)
//   - Manually fetches a new ad from the AdMob network.
//
// banner.showBanner(callback)
//   - Makes the banner visible on the screen.
//
// banner.hideBanner(callback)
//   - Hides the banner from the screen (does not destroy the instance).
//
// banner.bannerIsReady(callback)
//   - Checks if an ad has been successfully loaded and is ready to show.
//
// banner.bannerIsVisible(callback)
//   - Checks if the banner is currently visible to the user.

// ============================================================================
// CALLBACK RESPONSE FIELDS
// ============================================================================
// resp.event: string — one of:
//   "DID_FINISH_SETUP"       — the banner finished setting up and is ready to load an ad.
//   "DID_SHOW_BANNER"        — the banner was successfully shown.
//   "DID_HIDE_BANNER"        — the banner was successfully hidden.
//   "DID_LOAD_AD"            — ad loading finished; the banner is ready to be displayed.
//   "DID_RECORD_CLICK"       — the user clicked on the banner.
//   "DID_FAIL_TO_RECEIVE_AD" — loading the ad failed.
//   "DID_RECORD_IMPRESSION"  — the user saw the ad.

// --- AdMob Banner. Quick Start (Automatic Handling) Example. Start ---
// Setting preloadAd and showAd to true handles loading and showing automatically.

// Google's official test ad unit IDs — safe to use during development,
// always return test ads. Replace with your own before release.
const androidUnitId = "ca-app-pub-3940256099942544/6300978111";
const iOSUnitId = "ca-app-pub-3940256099942544/2934735716";

const bannerConfig = {
  androidUnitId,
  iOSUnitId,
  position: "BOTTOM",
  sizeType: "AUTO"
};

const onBannerEvent = function (resp) {
  console.log("Banner event:", resp.event);
};

const preloadAd = true;
const showAd = true; // only works because preloadAd is also true

const banner = new NativelyAdmobBanner(
  bannerConfig,
  onBannerEvent,
  preloadAd,
  onBannerEvent,
  showAd,
  onBannerEvent
);

// --- AdMob Banner. Quick Start (Automatic Handling) Example. End ---


// --- AdMob Banner. Manual Control Example. Start ---
// Use this when you need to control exactly when the ad loads and shows.

const manualConfig = {
  androidUnitId, // Google's official test ID, defined above
  iOSUnitId,      // Google's official test ID, defined above
  position: "BOTTOM",
  sizeType: "AUTO"
};

const lifecycleHandler = function (resp) {
  if (resp.event === "DID_FINISH_SETUP") {
    manualBanner.loadAd();
  }
  if (resp.event === "DID_LOAD_AD") {
    manualBanner.showBanner();
  }
  if (resp.event === "DID_FAIL_TO_RECEIVE_AD") {
    console.warn("Ad failed to load.");
  }
};

const manualPreloadAd = false; // loading manually instead
const manualShowAd = false;    // showing manually instead

const manualBanner = new NativelyAdmobBanner(
  manualConfig,
  lifecycleHandler,
  manualPreloadAd,
  lifecycleHandler,
  manualShowAd,
  lifecycleHandler
);

// --- AdMob Banner. Manual Control Example. End ---
```

{% endtab %}

{% tab title="AI Agents" %}
AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.&#x20;

Copy the line below and paste it into your AI agent.&#x20;

<pre><code>[<a data-footnote-ref href="#user-content-fn-1">Your feature description</a>] using the Natively AdMob Banner SDK: new NativelyAdmobBanner(config, setupCallback, preloadAd, preloadCallback, showAd, showCallback) — config.androidUnitId/config.iOSUnitId: ad unit IDs, default to Google's official test IDs ("ca-app-pub-3940256099942544/6300978111" Android, "ca-app-pub-3940256099942544/2934735716" iOS) if omitted. config.position: "TOP" or "BOTTOM". config.sizeType: "AUTO" or "CUSTOM" (with config.custom_width/config.custom_height used only for CUSTOM). preloadAd: boolean, automatically loads the ad after setup. showAd: boolean, automatically shows the ad after a successful load — only takes effect if preloadAd is also true. banner.loadAd(callback), banner.showBanner(callback), banner.hideBanner(callback), banner.bannerIsReady(callback), banner.bannerIsVisible(callback) are available for manual control. All callbacks return resp.event: "DID_FINISH_SETUP" / "DID_SHOW_BANNER" / "DID_HIDE_BANNER" / "DID_LOAD_AD" / "DID_RECORD_CLICK" / "DID_FAIL_TO_RECEIVE_AD" / "DID_RECORD_IMPRESSION". For reference: https://docs.buildnatively.com/natively-platform/features/admob
</code></pre>

{% hint style="warning" %}
Replace the placeholder at the beginning with a description of what you want to build - for example: "Show a banner ad at the bottom of the screen that loads and displays automatically".
{% endhint %}
{% endtab %}
{% endtabs %}

### Setup Logic (**Interstitial Ads**)

{% tabs %}
{% tab title="Bubble.io Plugin" %}

### \[Element] Natively - Admob Interstitial

{% hint style="warning" %}
This element must be set to **Visible on page load** to initialize correctly. Place it directly on the page root - not inside Popups, Floating Groups, Group Focus elements, or Repeating Groups. To hide it from your UI, set its dimensions to 0x0 px.
{% endhint %}

{% hint style="warning" %}
Only one **Natively - Interstitial** element can exist per page. Avoid reloading the page frequently, since each reload re-initializes the ad.
{% endhint %}

#### Fields:

* **iOS UnitId** - your ad unit ID, or Google's test ID (`ca-app-pub-3940256099942544/4411468910`).
* **Android UnitId** - your ad unit ID, or Google's test ID (`ca-app-pub-3940256099942544/1033173712`).
* **Auto Ad Reload** - automatically loads a new ad after the **Did dismiss ad** event. You'll be notified once it's ready via the **Did Load Ad** event.

{% hint style="info" %}
An ad must be fetched again after each time it's shown. If **Auto Ad Reload** is enabled, this happens automatically - listen for **Did Load Ad**. If disabled, listen for **Did dismiss ad** and call **Load Ad** manually.
{% endhint %}

#### Events:

* **Did Load Ad** - fires when the ad view has finished setup and is ready to be displayed.
* **Did record click** - fires when the user clicks on the ad.
* **Did fail to present** - fires when presenting the ad failed (can occur after **Show Ad**).
* **Did fail to load ad** - fires when loading the ad failed (can occur after **Load Ad**).
* **Did show ad** - fires when the ad view is displayed to the user.
* **Did dismiss ad** - fires when the user dismisses (closes) the ad view.
* **Did record impression** - fires when the user sees the ad.

#### States:

* **Interstitial Is Ready** - Yes/No. Whether the ad view is ready to be displayed.
* **Latest Error Message** - text description of the last error.
* **Latest Event** - the latest event code received from the app:
  * `DID_FAIL_TO_LOAD_AD` - loading the ad failed.
  * `DID_LOAD_AD` - the ad finished loading and is ready to display.
  * `DID_SHOW_AD` - the ad was displayed to the user.
  * `DID_RECORD_CLICK` - the user clicked on the ad.
  * `DID_FAIL_TO_PRESENT` - presenting the ad failed.
  * `DID_DISMISS_AD` - the user closed the ad view.
  * `DID_RECORD_IMPRESSION` - the user saw the ad.

#### Actions:

* **Show Ad** - displays the interstitial ad.
* **Load Ad** - loads a new ad manually.
* **Check Interstitial Ready** - checks whether the ad view is active and can be displayed.
  {% endtab %}

{% tab title="JavaScript SDK" %}

```javascript
// ============================================================================
// NATIVELY ADMOB INTERSTITIAL - DOCUMENTATION & EXAMPLES
// ============================================================================

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// new NativelyAdmobInterstitial(iOSUnitId, androidUnitId, setupCallback, autoAdReload, autoAdReloadCallback)
//   - Initializes the interstitial and loads the first ad automatically.
//   - iOSUnitId / androidUnitId: string — defaults to Google's test IDs if omitted.
//   - autoAdReload: boolean — automatically loads a new ad after the user
//     dismisses the current one. Default false.
//
// interstitial.loadAd(callback)
//   - Manually fetches a new ad from the network.
//
// interstitial.showInterstitialAd(callback)
//   - Displays the ad over the current screen.
//
// interstitial.interstitialIsReady(callback)
//   - Checks if an ad is currently loaded and ready to display.

// ============================================================================
// CALLBACK RESPONSE FIELDS
// ============================================================================
// resp.event: string — one of:
//   "DID_FAIL_TO_LOAD_AD" — loading the ad failed.
//   "DID_LOAD_AD"         — the ad finished loading and is ready to display.
//   "DID_SHOW_AD"         — the ad was displayed to the user.
//   "DID_RECORD_CLICK"    — the user clicked on the ad.
//   "DID_FAIL_TO_PRESENT" — presenting the ad failed.
//   "DID_DISMISS_AD"      — the user closed the ad view.
//   "DID_RECORD_IMPRESSION" — the user saw the ad.

// --- AdMob Interstitial. Standard Usage (Auto-Reload) Example. Start ---
// The SDK automatically fetches the next ad as soon as the current one is closed.

// Google's official test ad unit IDs — safe to use during development,
// always return test ads. Replace with your own before release.
const iOSUnitId = "ca-app-pub-3940256099942544/1033173712";
const androidUnitId = "ca-app-pub-3940256099942544/4411468910";

const onInterstitialEvent = function (resp) {
  console.log("Interstitial event:", resp.event);

  if (resp.event === "DID_LOAD_AD") {
    console.log("Ad ready — enable your Show Ad button now.");
  }
  if (resp.event === "DID_DISMISS_AD") {
    console.log("User closed the ad. No need to call loadAd() — auto-reload handles it.");
  }
};

const autoReloadAd = true;

const interstitial = new NativelyAdmobInterstitial(
  iOSUnitId,
  androidUnitId,
  onInterstitialEvent,
  autoReloadAd,
  onInterstitialEvent
);

function triggerLevelCompleteAd() {
  interstitial.interstitialIsReady(function (resp) {
    if (resp.status) {
      interstitial.showInterstitialAd();
    } else {
      console.log("Ad not ready yet, skipping...");
    }
  });
}

// --- AdMob Interstitial. Standard Usage (Auto-Reload) Example. End ---


// --- AdMob Interstitial. Manual Control Example. Start ---
// Use this if you need strict control over when ads are loaded.

const manualHandler = function (resp) {
  if (resp.event === "DID_LOAD_AD") {
    console.log("Manual ad loaded. Ready to show.");
  }
  if (resp.event === "DID_DISMISS_AD") {
    console.log("Ad closed.");
    // Optionally load the next one immediately:
    // manualInterstitial.loadAd();
  }
};

const manualAutoReload = false; // loading manually instead

const manualInterstitial = new NativelyAdmobInterstitial(
  iOSUnitId,     // Google's official test ID, defined above
  androidUnitId, // Google's official test ID, defined above
  manualHandler,
  manualAutoReload,
  manualHandler
);

function prepareAd() {
  console.log("Pre-loading ad...");
  manualInterstitial.loadAd();
}

// --- AdMob Interstitial. Manual Control Example. End ---
```

{% endtab %}

{% tab title="AI Agents" %}
AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.&#x20;

Copy the line below and paste it into your AI agent.&#x20;

<pre><code>[<a data-footnote-ref href="#user-content-fn-1">Your feature description</a>] using the Natively AdMob Interstitial SDK: new NativelyAdmobInterstitial(iOSUnitId, androidUnitId, setupCallback, autoAdReload, autoAdReloadCallback) — only one instance can be used per page. iOSUnitId/androidUnitId: ad unit IDs, default to Google's official test IDs ("ca-app-pub-3940256099942544/1033173712" iOS, "ca-app-pub-3940256099942544/4411468910" Android) if omitted. autoAdReload: boolean, automatically loads a new ad after the user dismisses the current one. interstitial.loadAd(callback), interstitial.showInterstitialAd(callback), interstitial.interstitialIsReady(callback) are available for manual control. All callbacks return resp.event: "DID_FAIL_TO_LOAD_AD" / "DID_LOAD_AD" / "DID_SHOW_AD" / "DID_RECORD_CLICK" / "DID_FAIL_TO_PRESENT" / "DID_DISMISS_AD" / "DID_RECORD_IMPRESSION". For reference: https://docs.buildnatively.com/natively-platform/features/admob
</code></pre>

{% hint style="warning" %}
Replace the placeholder at the beginning with a description of what you want to build - for example: "Show an interstitial ad when the user completes a level, with automatic ad reloading".
{% endhint %}
{% endtab %}
{% endtabs %}

### How to use

#### Remember the Preload/Show dependency for Banner

`showAd` (or **Show Ad on Initialize** in Bubble) only takes effect if `preloadAd` is also enabled - showing requires the ad to have already loaded. If you want manual control, disable both and call `loadAd()` then `showBanner()` yourself.

#### Always reload Interstitial ads after they're shown

An interstitial ad is single-use - once dismissed, you need a new one. Enable auto-reload (**Auto Ad Reload** in Bubble, or the `autoAdReload` parameter in the JS SDK) to have this happen automatically, or manually call `loadAd()` after the ad is dismissed.

#### Only one Interstitial instance per page

Creating multiple `NativelyAdmobInterstitial` instances on the same page - or reloading the page frequently while one is active - can cause unexpected behavior.

#### Check readiness before showing an ad

Call `bannerIsReady()` or `interstitialIsReady()` (or the corresponding **Check Banner Ready** / **Check Interstitial Ready** action in Bubble) before showing an ad, to avoid trying to display one that hasn't finished loading yet.

## Testing

{% hint style="danger" %}
Never click your own **live** ads - this violates AdMob policy. Choose one of the two approaches below, depending on what you're testing.
{% endhint %}

### Quick testing with sample ads

Use Google's official test unit IDs - they always return test ads, regardless of whether the device is registered as a test device. Safe to use on any device without violating AdMob policy.

#### Banner:

* iOS - `ca-app-pub-3940256099942544/2934735716` .
* Android - `ca-app-pub-3940256099942544/6300978111` .

#### Interstitial:

* iOS - `ca-app-pub-3940256099942544/1033173712` .
* Android - `ca-app-pub-3940256099942544/4411468910` .

### Test device for live ads

If you want to preview how your actual, real ad units will render before going live, register your device in AdMob, then use your real ad unit IDs while testing on that device. Registered test devices see real ad content marked as a test, without risking policy violations from real clicks or impressions.

1. In AdMob, go to **Settings** > **Test devices**.
2. Click **Add Test Device**.
3. Enter your device name and [Advertising ID/IDFA](https://support.google.com/admob/answer/9691433?hl=en#ID).
4. In your Bubble plugin fields or JavaScript code, replace the sample test unit IDs with your real **Ad Unit IDs** - created in the [AdMob Ad Units configuration](#admob-a-d-units-configuration) above.

{% hint style="warning" %}
Real ad units will still serve real ads to any device that isn't registered as a test device - only use your real IDs on a registered test device until you're ready to release.
{% endhint %}

<div><figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FPbHn3rdwJJ1XuQsfqQ18%252Ftesting-1.png%3Falt%3Dmedia%26token%3D0ac51312-5567-4b8c-8bbe-a225a4f69cd3&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=918d8072&#x26;sv=2" alt=""><figcaption><p>Steps 1-2</p></figcaption></figure> <figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FJScTyUEhmY8Cf1lBS3Y8%252Ftesting-2.png%3Falt%3Dmedia%26token%3D91770901-c594-41c3-ab02-6390c32de47d&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=5620ef44&#x26;sv=2" alt=""><figcaption><p>Step 3</p></figcaption></figure></div>

For AdMob's full app testing guides, see [iOS testing](https://developers.google.com/admob/ios/test-ads) and [Android testing](https://developers.google.com/admob/android/next-gen/test-ads).

## Release

Once your ads are tested and behaving as expected, the last steps are to switch to live ad units, publish your app, and formally connect it to AdMob - without this final connection, your app will not serve real ads even after it's live in the stores.

{% stepper %}
{% step %}

#### Switch to live ad units

Swap the test IDs in your Bubble plugin fields or JavaScript code for your real **Ad Unit IDs**, created in the [AdMob Ad Units configuration](#admob-a-d-units-configuration) above.

{% hint style="warning" %}
Double-check you've replaced test IDs in every **Banner** and **Interstitial** element or SDK call before submitting - a build shipped with test IDs will only ever serve test ads to real users.
{% endhint %}
{% endstep %}

{% step %}

#### Submit and publish your app

Submit your app to the App Store and Google Play as you normally would. See [Testing & Submitting your app](/guides/testing-and-submitting-your-app.md) for the full release process.
{% endstep %}

{% step %}

#### Link your live listing to AdMob

Once your app is approved and published on the App Store and/or Google Play:

1. Go to **Apps** > \[your app] > **App Settings** in AdMob.
2. Click **Add Store**.
3. Connect your App Store and/or Google Play listing.

{% hint style="info" %}
This step is required for real ads to serve. Review can take about a day - during that window, ad requests from your live app may return no fill or fall back to test behavior.
{% endhint %}

<figure><img src="https://docs.buildnatively.com/~gitbook/image?url=https%3A%2F%2F3352617162-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F90tV7pYflEQdiAr2VfWu%252Fuploads%252FClJBqizoXseptHyMr1uM%252Fimage.png%3Falt%3Dmedia%26token%3Df22d9adc-3baa-4ba7-9e56-aaa22e5bcead&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=b101fc79&#x26;sv=2" alt="" width="375"><figcaption><p>Step 2</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Troubleshooting

<details>

<summary>No ads are showing, even with test unit IDs</summary>

Confirm the feature is enabled and your App IDs are correctly entered under **Features** > **AdMob**, then confirm the app has been rebuilt - AdMob configuration changes only take effect after a rebuild

</details>

<details>

<summary>Banner never appears, even though <code>showAd</code> / <strong>Show Ad on Initialize</strong> is enabled</summary>

Confirm `preloadAd` (or **Preload Ad on Initialize**) is also enabled - showing an ad only happens automatically if the ad has been preloaded first. If you want manual control instead, disable both and call `loadAd()` followed by `showBanner()` yourself.

</details>

<details>

<summary>Interstitial ad fails to show, or <code>showInterstitialAd()</code> does nothing</summary>

Confirm `interstitialIsReady()` returns `true` before calling `showInterstitialAd()`. Showing an ad that hasn't finished loading fails silently or triggers `DID_FAIL_TO_PRESENT` .

</details>

<details>

<summary>No new interstitial ad appears after the previous one was dismissed</summary>

An interstitial ad is single-use. Confirm **Auto Ad Reload** / `autoAdReload` is enabled, or manually call `loadAd()` after `DID_DISMISS_AD`.

</details>

<details>

<summary>Multiple Interstitial ads misbehave, or events fire unexpectedly</summary>

Only one `NativelyAdmobInterstitial` instance is supported per page. Check that you haven't created more than one, and avoid reloading the page frequently while an interstitial is active.

</details>

<details>

<summary>Real ads don't show after publishing</summary>

Confirm you've linked your live App Store / Google Play listing to AdMob under **Apps** > **\[Your App** > **App Settings** > **Add Store**. This step is required for real ads to serve and can take about a day to process.

</details>

<details>

<summary>App rejected by Apple for vague tracking permission text</summary>

The **Permission Description** (iOS only) must clearly explain why your app requests tracking. Avoid vague text like "to improve the app" - be specific, e.g., "We use your data to provide personalized advertisements that are relevant to your interests."

</details>

<details>

<summary>Not working in a web browser or the Natively Preview app</summary>

AdMob is a native feature and does not work in a standard web browser or in the Natively Preview app. Test on a real device using a full Natively build.

</details>

[^1]: Replace this placeholder