google-mobile-ads-interstitial

# AI Integration Agent Instructions for Interstitial Ads

## Required Imports

Use the following imports to implement an interstitial ad:

```
import com.google.android.libraries.ads.mobile.sdk.common.AdRequest
import com.google.android.libraries.ads.mobile.sdk.common.AdLoadCallback
import com.google.android.libraries.ads.mobile.sdk.common.FullScreenContentError
import com.google.android.libraries.ads.mobile.sdk.common.LoadAdError
import com.google.android.libraries.ads.mobile.sdk.interstitial.InterstitialAd
import com.google.android.libraries.ads.mobile.sdk.interstitial.InterstitialAdEventCallback
```

## Method Signatures

Use the following method signatures to implement interstitial ads:

The `AdRequest` object takes the ad unit ID:

```
AdRequest.Builder(adUnitId: String).build()
```

The method signature to load an ad from `InterstitialAd`:

```
fun load(
    adRequest: AdRequest,
    adLoadCallback: AdLoadCallback<InterstitialAd>
): Unit
```

The `AdLoadCallback` interface is defined as:

```
interface AdLoadCallback<T> {
    fun onAdLoaded(ad: T): Unit
    fun onAdFailedToLoad(adError: LoadAdError): Unit
}
```

## Gotchas

**UI Threading**: **MANDATORY**: Callbacks in GMA-Next Gen SDK are invoked on a
background thread. **ALL UI-RELATED OPERATIONS** (e.g., Toasts, View updates,
Fragment transactions) **MUST** be wrapped in `runOnUiThread {}` or
`Dispatchers.Main.launch {}` within GMA SDK callbacks. SKIPPING THIS STEP WILL
CAUSE THE APPLICATION TO CRASH.

## Interstitial ad workflow

1.  **Load the ad**

2.  **Register for ad event callbacks**
    -   [ ] Set the `adEventCallback` on the `InterstitialAd` object.
        *   Drop the reference to the interstitial ad when the ad is dismissed
            or fails to show.

3.  **Show the ad**

4.  **Verify the implementation**: Verify the build to ensure there are no
    compile errors:
    -   [ ] Run `gradle build -x test` to confirm a successful clean build.
        Resolve any GMA SDK related compile errors.

### Links

Additional documentation:

-   https://developers.google.com/admob/android/next-gen/interstitial.md.txt

# AI Integration Agent Instructions for Interstitial Ads

## Gotchas

Google Mobile Ads SDK uses `NS_SWIFT_NAME` macros to provide idiomatic Swift
names.

## Interstitial ad workflow

1.  **Load the ad**
    *   For Swift code, use `async/await` instead of a completion handler.

2.  **Register for ad event callbacks**
    -   [ ] Set the `fullScreenContentDelegate` on the `InterstitialAd` object.
        *   Drop the reference to the interstitial ad when the ad is dismissed
            or fails to show.

3.  **Show the ad**
    *   **ViewController Parameter:** The `rootViewController` parameter in the
    `present(from:)` method is an optional parameter and can be set to `nil`.

4.  **Verify the implementation**: Verify the build to ensure there are no
    compile errors:
    -   **If `xcodebuild` is available**: Run `xcodebuild` to programmatically
        verify that the iOS project compiles properly with the GMA SDK. Resolve
        any GMA-SDK related compile errors.
    -   **If `xcodebuild` is NOT available**: Output instructions directing the
        user to build the project in Xcode and manually verify there are no
        compile errors.

### Links

Additional documentation:

-   https://developers.google.com/admob/ios/interstitial.md.txt

# AI Integration Agent Instructions for Unity Interstitial Ads

## Required Imports

Use the following imports to implement an interstitial ad:

```c#
using System;
using UnityEngine;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
```

## Interstitial Ad Workflow

1.  **Load the ad**:

    Use the static `InterstitialAd.Load()` method passing the ad unit ID,
    an `AdRequest` object, and a completion callback
    (`Action<InterstitialAd, LoadAdError>`):

    ```c#
    // Test ad unit IDs. Replace with your own ad unit IDs.
    #if UNITY_ANDROID
        string adUnitId = "ca-app-pub-3940256099942544/1033173712";
    #elif UNITY_IPHONE
        string adUnitId = "ca-app-pub-3940256099942544/4411468910";
    #else
        string adUnitId = "unused";
    #endif
    ```

    ```c#
    InterstitialAd.Load(adUnitId, new AdRequest(),
        (InterstitialAd ad, LoadAdError error) =>
        {
            if (error != null || ad == null)
            {
                // Handle the error.
                return;
            }
            interstitialAd = ad;
        });
    ```

    Always destroy any existing `InterstitialAd` object before loading a new ad.

2.  **Register for ad event callbacks**:

    Subscribing to ad events on the `InterstitialAd` object is optional and
    depends on your application requirements:

    -   `OnAdPaid`: Subscribe to log estimated ad revenue (`AdValue`) for
        impression-level ad monetization tracking.
    -   `OnAdImpressionRecorded`: Subscribe to track ad impressions in
        internal telemetry or third-party analytics platforms.
    -   `OnAdClicked`: Subscribe to record user clicks on the ad.
    -   `OnAdFullScreenContentOpened`: Subscribe to pause game audio,
        timers, or gameplay loops when the interstitial ad covers the screen.
    -   `OnAdFullScreenContentClosed`: Subscribe to resume game audio or
        gameplay loops when the ad is dismissed. Destroy the `InterstitialAd`
        object (`interstitialAd.Destroy()`) and reload another ad
        (`InterstitialAd.Load()`) so a fresh ad is ready for the next
        transition point.
    -   `OnAdFullScreenContentFailed`: Subscribe to log display errors if the
        interstitial ad fails to show.

    Ensure background ad callbacks interacting with Unity objects
    (`UnityEngine`) are explicitly scheduled on the main thread using
    `MobileAdsEventExecutor.ExecuteInUpdate()`, because Unity APIs are not
    thread-safe and must be called from the main thread.

    ```c#
    interstitialAd.OnAdFullScreenContentOpened += () =>
    {
        MobileAdsEventExecutor.ExecuteInUpdate(() =>
        {
            // Interact with UnityEngine objects on the main thread here.
        });
    };
    ```

3.  **Show the ad**:

    Check `CanShowAd()` on the `InterstitialAd` object before calling the
    `Show()` method. Include a null check to avoid exceptions.

    ```c#
    if (interstitialAd != null && interstitialAd.CanShowAd())
    {
        interstitialAd.Show();
    }
    ```

4.  **Verify the implementation**: Ensure there are no compilation errors:
    -   [ ] Verify the Unity Console has no C# script compile errors or
        missing GoogleMobileAds namespace references.

### Links

Additional documentation:

-   https://developers.google.com/admob/unity/interstitial.md.txt

---
name: google-mobile-ads-interstitial
description: >-
  Provides instructions for implementing, integrating, or configuring Google
  Mobile Ads (GMA) SDK interstitial ads in Android, iOS, or Unity mobile
  applications. Use when the task involves setting up interstitial ads. Don't
  use for "rewarded interstitial" ads.
metadata:
  version: 1.1.0
  category: GoogleAds
---
# Google Mobile Ads SDK - Interstitial Ads

Interstitial ads show full-page ads for users on mobile apps. Interstitial ads
are designed to be placed between content and are best placed at natural app
transition points.

## Workflow

1.  **Determine the user's platform**: Identify if the project is Android,
    iOS, or Unity. If unclear, ask before proceeding.

2.  **Read the platform guide** for implementation details:
    -   Android: `references/android-interstitial.md`
    -   iOS: `references/ios-interstitial.md`
    -   Unity: `references/unity-interstitial.md`

3.  **Follow these steps in order**:
    -   [ ] Load the ad
    -   [ ] Register for ad event callbacks
    -   [ ] Show the ad
    -   [ ] Verify the implementation