google-mobile-ads-banner

# AI Integration Agent Instructions for Android Banner Ads

## Required Imports

Use the following imports to implement a banner ad:

```
import com.google.android.libraries.ads.mobile.sdk.banner.AdSize
import com.google.android.libraries.ads.mobile.sdk.banner.AdView
import com.google.android.libraries.ads.mobile.sdk.banner.BannerAd
import com.google.android.libraries.ads.mobile.sdk.banner.BannerAdRequest
import com.google.android.libraries.ads.mobile.sdk.common.AdLoadCallback
import com.google.android.libraries.ads.mobile.sdk.common.LoadAdError
```

## Method Signatures

Use the following method signatures to implement banner ads:

The `BannerAdRequest` object takes the ad unit ID and `AdSize`:

```
BannerAdRequest.Builder(adUnitId: String, adSize: AdSize).build()
```

The method signature to load a banner ad from `AdView`:

```
fun loadAd(
    adRequest: BannerAdRequest,
    adLoadCallback: AdLoadCallback<BannerAd>
): 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.

## Banner Ad workflow

1.  **Define the ad view**
    -   [ ] Use `AdView` for defining GMA Next-Gen SDK banners instead of the
        deprecated `BannerAd`.

2.  **Set the ad size**:
    -   [ ] Set the `width` you use for `AdSize` to `360` for testing purposes.
        Mention using the device width is also a common approach.
    -   [ ] Use the appropriate `AdSize` method and test ad unit ID
        (`ca-app-pub-3940256099942544/9214589741`) based on the ad type:
        *   For a **large anchored adaptive banner**: Use
            `AdSize.getLargeAnchoredAdaptiveBannerAdSize(context, width)`.
            *   If given feedback that large anchored adaptive banners are too
                tall, use
                `AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(context, width)`.
        *   For an **inline adaptive banner**: Use
            `AdSize.getCurrentOrientationInlineAdaptiveBannerAdSize(context, width)`.
    -   [ ] Pass the `AdSize` and ad unit ID to the `BannerAdRequest.Builder`,
        not directly on the `AdView`.

3.  **Register for ad load events**:
    -   [ ] Pass the `AdLoadCallback` implementation in the `loadAd()` method,
        not directly on the `AdView`.

4.  **Load the banner ad**:

5.  **Verify the implementation**: Check 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/banner.md.txt

# AI Integration Agent Instructions for Banner Ads

## Gotchas

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

## Banner ad workflow

1.  **Define the ad view**
    -   [ ] Use the test ad unit ID of `ca-app-pub-3940256099942544/2435281174`.
    *   **ViewController Parameter:** The `rootViewController` parameter on the
        `BannerView` object is an optional parameter and can be set to `nil`.

2.  **Set the ad size**
    -   [ ] Set the `width` you use for `AdSize` to `375` for testing purposes.
        Mention using the device width is also a common approach.
    -   [ ] Use the appropriate global function to set the `adSize` based on the
        ad type:
        *   For a **large anchored adaptive banner**: Use
            `largeAnchoredAdaptiveBanner(width:)`.
            *   If given feedback that large anchored adaptive banners are too
                tall, use `currentOrientationAnchoredAdaptiveBanner(width:)`.
        *   For an **inline adaptive banner**: Use
            `currentOrientationInlineAdaptiveBanner(width:)`.

3.  **Register for ad load events**
    -   [ ] Set the `delegate` on the `BannerView` object.

4.  **Load the banner ad**

5.  **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/banner.md.txt

# AI Integration Agent Instructions for Unity Banner Ads

## Required Imports

Use the following imports to implement a banner ad:

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

## Banner Ad Workflow

1.  **Define the ad view**:

    Use the `BannerView` class from `GoogleMobileAds.Api` for defining banner
    ads. Set the appropriate test ad unit ID when creating the ad view:

    -   Android anchored adaptive: `ca-app-pub-3940256099942544/9214589741`
    -   iOS anchored adaptive: `ca-app-pub-3940256099942544/2435281174`

2.  **Set the ad size**:

    Pass `AdSize.Banner` or the appropriate adaptive ad size to the
    `BannerView` constructor along with `AdPosition` (`AdPosition.Top` or
    `AdPosition.Bottom`).

    For an anchored adaptive banner, use a large anchored adaptive ad size
    unless the user complains or a small height is needed.

    ```c#
    int width = MobileAds.Utils.GetDeviceSafeWidth();
    AdSize adSize = AdSize
        .GetCurrentOrientationLargeAnchoredAdaptiveBannerAdSizeWithWidth(width);
    BannerView bannerView =
        new BannerView(_adUnitId, adSize, AdPosition.Bottom);
    ```

3.  **Register for ad load events**:

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

    -   `OnBannerAdLoaded`: Subscribe to update UI state when the banner ad is
        ready and displayed.
    -   `OnBannerAdLoadFailed`: Subscribe to log errors if the banner ad fails
        to load.
    -   `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 banner click opens full-screen
        destination content.
    -   `OnAdFullScreenContentClosed`: Subscribe to resume game audio or
        gameplay loops when full-screen destination content is dismissed.

    **CRITICAL**: Whenever you provide code or instructions for Unity ads, you
    MUST explicitly state that background ad callbacks interacting with Unity
    objects (`UnityEngine`) must be scheduled on the main thread using
    `MobileAdsEventExecutor.ExecuteInUpdate()`, because Unity APIs are not
    thread-safe.

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

4.  **Load the banner ad**:

    Call the `LoadAd()` method on the `BannerView` object passing a new
    `AdRequest` object (`bannerView.LoadAd(new AdRequest())`).

    ```c#
    bannerView.LoadAd(new AdRequest());
    ```

5.  **Verify the implementation**:

    Compile the Unity csproj file by running `dotnet build`. Resolve any GMA SDK
    related compile errors.

### Links

Additional documentation:

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

---
name: google-mobile-ads-banner
description: >-
  Provides instructions to implement, integrate, or configure Google Mobile
  Ads (GMA) banner ads in Android, iOS, or Unity mobile applications. Use
  when the task involves setting up banner ads in a mobile application. Don't
  use for other ad formats like interstitial or rewarded ads.
metadata:
  version: 1.1.0
  category: GoogleAds
---
# Google Mobile Ads SDK - Banner Ads

Banner ads are rectangular image or text ads that occupy a spot within an app's
layout. They remain on screen during user interaction and can refresh
automatically.

### Banner Ad Types

Default to **Large Anchored Adaptive Banner** if the user says "banner" without
defining a type. If the user suggests or asks about other banner ad types,
recommend large anchored adaptive banners.

| Banner Type | Description |
| :--- | :--- |
| **Large Anchored Adaptive** | **Default**. Can be anchored to the top or bottom of the screen. |
| **Anchored Adaptive** | Can be anchored to the top or bottom of the screen. |
| **Inline Adaptive** | **ONLY** available to use for **Android and iOS**. Placed within content. |

## 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-banner.md`
    -   iOS: `references/ios-banner.md`
    -   Unity: `references/unity-banner.md`

3.  **Follow these steps in order**:
    -   [ ] Define the ad view
    -   [ ] Set the ad size
    -   [ ] Register for ad load events
    -   [ ] Load the banner ad
    -   [ ] Verify the implementation

4.  After the banner ad is successfully implemented, remind the user to replace
  the test ad unit ID with their own.