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 7.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:
- Create a utility class that loads an ad before you need to display it.
- Load an ad.
- Register for callbacks and show the ad.
- Listen to
AppStateEventNotifier.AppStateChanged
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;
}));
}
}
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, we recommend listening to
the AppStateEventNotifier
singleton. By implementing the
AppStateEventNotifier.AppStateChanged
delegate, your app will be alerted to app
launch and foregrounding events and will be able to show the ad.
AppStateEventNotifier
is recommended because OnApplicationPause
will give
false foreground and background signals when the app shows a full screen ad.
using UnityEngine;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
public void Start()
{
// Load an app open ad when the scene starts
AppOpenAdManager.Instance.LoadAd();
// Listen to application foreground and background events.
AppStateEventNotifier.AppStateChanged += OnAppStateChanged;
}
private void OnAppStateChanged(AppState state)
{
// Display the app open ad when the app is foregrounded.
UnityEngine.Debug.Log("App State is " + state);
if (state == AppState.Foreground)
{
AppOpenAdManager.Instance.ShowAdIfAvailable();
}
}
}
Consider ad expiration
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.
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. - On the iOS platform, AppStateEventNotifier instantiates an AppStateEventClient GameObject. This GameObject is required for events to fire, please do not Destroy it. Events will stop firing if the Game Object is destroyed.