App Open Ads

App open ads are a special ad format intended for publishers wishing 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.

App open ads automatically show a small branding area so users know they're in your app. Here is an example of what an app open ad looks like:

Prerequisites

• Unity plugin 6.1.0 or higher.
• Complete Get Started. Your Unity app should already have the Google Mobile Ads Unity plugin imported.

Always test with test ads

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

The easiest way to load test ads is to use our dedicated test ad unit IDs for Android and iOS rewarded ads:

Android

ca-app-pub-3940256099942544/3419835294

iOS

ca-app-pub-3940256099942544/5662855259

They have been specially configured to return test ads for every request, and you're free to use them in your own apps while coding, testing, and debugging. Just make sure you replace them with your own ad unit ID before publishing your app.

For more information about how the Mobile Ads SDK's test ads work, see Test Ads.

Implementation

The main steps to integrate app open ads are:

1. Create a utility class that loads an ad before you need to display it.
2. Load an ad.
3. Register for callbacks and show the ad.
4. Listen for MonoBehavior.OnApplicationPause(bool) to show the ad during foregrounding events.

Create a utility class

Create a new class called AppOpenAdManager to load the ad. This class manages an instance variable to keep track of a loaded ad and the ad unit ID for each platform.

using System;
using GoogleMobileAds.Api;
using UnityEngine;

public class AppOpenAdManager
{
    #if UNITY_ANDROID
    private const string AD_UNIT_ID = "ca-app-pub-3940256099942544/3419835294";
    #elif UNITY_IOS
    private const string AD_UNIT_ID = "ca-app-pub-3940256099942544/5662855259";
    #else
    private const string AD_UNIT_ID = "unexpected_platform";
    #endif

    private static AppOpenAdManager instance;

    private AppOpenAd ad;

    private bool isShowingAd = false;

    public static AppOpenAdManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = new AppOpenAdManager();
            }

            return instance;
        }
    }

    private bool IsAdAvailable
    {
        get
        {
            return ad != null;
        }
    }

    public void LoadAd()
    {
        // We will implement this below.
    }
}

Load an ad

Your app open ad needs to be ready before users enter into your app. Implement a utility class to make ad requests ahead of when you need to show the ad.

Loading an ad is accomplished using the static LoadAd() method on the AppOpenAd class. The load method requires an ad unit ID, a ScreenOrientation mode, an AdRequest object, and a completion handler which gets called when ad loading succeeds or fails. The loaded AppOpenAd object is provided as a parameter in the completion handler. The example below shows how to load an AppOpenAd.

public class AppOpenAdManager
{
    ...

    public void LoadAd()
    {
        AdRequest request = new AdRequest.Builder().Build();

        // Load an app open ad for portrait orientation
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                // Handle the error.
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            // App open ad is loaded.
            ad = appOpenAd;
        }));
    }
}

Warning: Attempting to load a new ad from the ad load callback is strongly discouraged. If you must load an ad from the callback, limit ad load retries to avoid continuous failed ad requests in situations such as limited network connectivity.

Show the ad and handle fullscreen callbacks

Before showing the ad, register the delegate for each event handler to listen to each ad event.

public class AppOpenAdManager
{
    ...

    public void ShowAdIfAvailable()
    {
        if (!IsAdAvailable || isShowingAd)
        {
            return;
        }

        ad.OnAdDidDismissFullScreenContent += HandleAdDidDismissFullScreenContent;
        ad.OnAdFailedToPresentFullScreenContent += HandleAdFailedToPresentFullScreenContent;
        ad.OnAdDidPresentFullScreenContent += HandleAdDidPresentFullScreenContent;
        ad.OnAdDidRecordImpression += HandleAdDidRecordImpression;
        ad.OnPaidEvent += HandlePaidEvent;

        ad.Show();
    }

    private void HandleAdDidDismissFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Closed app open ad");
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        isShowingAd = false;
        LoadAd();
    }

    private void HandleAdFailedToPresentFullScreenContent(object sender, AdErrorEventArgs args)
    {
        Debug.LogFormat("Failed to present the ad (reason: {0})", args.AdError.GetMessage());
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        LoadAd();
    }

    private void HandleAdDidPresentFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Displayed app open ad");
        isShowingAd = true;
    }

    private void HandleAdDidRecordImpression(object sender, EventArgs args)
    {
        Debug.Log("Recorded ad impression");
    }

    private void HandlePaidEvent(object sender, AdValueEventArgs args)
    {
        Debug.LogFormat("Received paid event. (currency: {0}, value: {1}",
                args.AdValue.CurrencyCode, args.AdValue.Value);
    }
}

If a user returns to your app after having left it by clicking on an app open ad, make sure they’re not presented with another app open ad.

Listen for app foregrounding events

In order to be notified of app foregrounding events, you need to listen to the application pause message. By implementing MonoBehavior.OnApplicationPause(bool) method, your app will be alerted to app launch and foregrounding events and be able to show the ad.

using UnityEngine;

using GoogleMobileAds.Api;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{

    public void Start()
    {
        // Load an app open ad when the scene starts
        AppOpenAdManager.Instance.LoadAd();
    }

    public void OnApplicationPause(bool paused)
    {
        // Display the app open ad when the app is foregrounded
        if (!paused)
        {
            AppOpenAdManager.Instance.ShowAdIfAvailable();
        }
    }
}

Consider ad expiration

Key Point: Ad references in the app open beta will time out after four hours. Ads rendered more than four hours after request time will no longer be valid and may not earn revenue. This time limit is being carefully considered and may change in future beta versions of the app open format.

To ensure you don't show an expired ad, add a method to the AppOpenAdManager that checks how long it has been since your ad loaded. Then, use that method to check if the ad is still valid.

public class AppOpenAdManager
{
    ...
    private DateTime loadTime;

    private bool IsAdAvailable
    {
        get
        {
            return ad != null && (System.DateTime.UtcNow - loadTime).TotalHours < 4;
        }
    }

    public void LoadAd()
    {
        if (IsAdAvailable)
        {
            return;
        }

        AdRequest request = new AdRequest.Builder().Build();
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            ad = appOpenAd;
            loadTime = DateTime.UtcNow;
        }));
    }
}

Cold starts and loading screens

The documentation thus far assumes that you only show app open ads when users foreground your app when it is suspended in memory. "Cold starts" occur when your app is launched but was not previously suspended in memory.

An example of a cold start is when a user opens your app for the first time. With cold starts, you won't have a previously loaded app open ad that's ready to be shown right away. The delay between when you request an ad and receive an ad back can create a situation where users are able to briefly use your app before being surprised by an out of context ad. This should be avoided because it is a bad user experience.

The preferred way to use app open ads on cold starts is to use a loading screen to load your game or app assets, and to only show the ad from the loading screen. If your app has completed loading and has sent the user to the main content of your app, do not show the ad.

Key Point: In order to continue loading app assets while the app open ad is being displayed, always load assets in a background thread.

Best practices

App open ads help you monetize your app's loading screen, when the app first launches and during app switches, but it's important to keep best practices in mind so that your users enjoy using your app. It's best to:

• Show your first app open ad after your users have used your app a few times.
• Show app open ads during times when your users would otherwise be waiting for your app to load.
• If you have a loading screen under the app open ad, and your loading screen completes loading before the ad is dismissed, you may want to dismiss your loading screen in the OnAdDidDismissFullScreenContent event handler.