Load a single app open ad

SDK with single-load API.

App open ads are a special ad format intended for publishers who want to monetize their app load screens. App open ads can be closed at any time, and are designed to be shown when your users bring your app to the foreground.

For more information, see App open ad guidance.

This guide explains how to integrate app open ads into an Android app.

Prerequisites

Set up GMA Next-Gen SDK.

Always test with test ads

When building and testing your apps, make sure that you use test ads rather than live, production ads. Failure to do so can lead to suspension of your account.

To load test ads, use the dedicated test ad unit ID for Android app open ads:

ca-app-pub-3940256099942544/9257395921

This ad unit ID has been specially configured to return test ads for every request. You're free to use it in your own apps while coding, testing, and debugging. Make sure that you replace it with your own ad unit ID before publishing your app.

For details on GMA Next-Gen SDK test ads, see Enable test ads.

Load an ad

The following example shows you how to load a single ad:

Kotlin

// Load ads after you initialize MobileAds.
AppOpenAd.load(
  AdRequest.Builder(adUnitId).build(),
  object : AdLoadCallback<AppOpenAd> {
    override fun onAdLoaded(ad: AppOpenAd) {
      // App open ad loaded.
      appOpenAd = ad
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      // App open ad failed to load.
      Log.e(TAG, "App open ad failed to load: ${adError.message}")
      appOpenAd = null
    }
  },
)

Java

// Load ads after you initialize MobileAds.
AppOpenAd.load(
    new AdRequest.Builder(adUnitId).build(),
    new AdLoadCallback<AppOpenAd>() {
      @Override
      public void onAdLoaded(AppOpenAd ad) {
        // App open ad loaded.
        appOpenAd = ad;
      }

      @Override
      public void onAdFailedToLoad(LoadAdError adError) {
        // App open ad failed to load.
        Log.e(TAG, "App open ad failed to load: " + adError.getMessage());
        appOpenAd = null;
      }
    });

When testing, use the test ad unit ID: ca-app-pub-3940256099942544/9257395921.

Show the ad

To show an app open ad, use the show method.

Kotlin

private fun showAd(appOpenAd: AppOpenAd, activity: Activity) {
  // Show the ad.
  appOpenAd.show(activity)
}

Java

private void showAd(AppOpenAd appOpenAd, Activity activity) {
  // Show the ad.
  appOpenAd.show(activity);
}

Listen to ad events

Before showing the ad, listen to ad lifecycle events:

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = appOpenAd
  if (ad == null) {
    Log.e(TAG, "App open ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // App open ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // App open ad did dismiss.
        appOpenAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // App open ad failed to show.
        Log.e(TAG, "App open ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // App open ad did record an impression.
      }

      override fun onAdClicked() {
        // App open ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (appOpenAd == null) {
    Log.e(TAG, "App open ad is not ready yet.");
    return;
  }

  appOpenAd.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // App open ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // App open ad did dismiss.
          appOpenAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // App open ad failed to show.
          Log.e(TAG, "App open ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // App open ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // App open ad did record a click.
        }
      });
}

Cold starts and loading screens

A cold start occurs when your app launches from scratch, for example, when a user opens your app for the first time or after memory termination. During a cold start, you lack a previously loaded app open ad ready to show right away.

Due to ad request delays, users might interact with your app before an app open ad appears. To avoid a poor user experience, show app open ads on cold starts strictly from a loading screen while app assets load. If asset loading completes and the user reaches the main content before the ad loads, don't show the ad.

Load app assets on a background thread so that loading continues while the ad is displayed.

Best practices

Follow these best practices for app open ads:

  • Show your first app open ad only after a user opens your app several times.
  • Show app open ads only while users wait for your app to load.
  • If your loading screen finishes loading while the ad is displayed, dismiss the loading screen in the ad dismissed callback method.