Using Ad Placements

This guide shows you how to use the Google Mobile Ads Unity plugin's Ad Placements feature to create and display ads for your app.

Prerequisites

• Unity 2017.4 or higher.

• Unity plugin prerequisites.

• Download and import the early build of GMA Unity plugin.

• Set your AdMob app ID in the Unity Editor.

Initialize the Google Mobile Ads SDK

Before loading ads, initialize the Mobile Ads SDK by calling MobileAds.Initialize(), with an Action<InitializationStatus> callback. This needs to be done only once, ideally at app launch.

using GoogleMobileAds.Api;
using System.Collections.Generic;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    ...
    public void Start()
    {
        // Initialize the Mobile Ads SDK.
        MobileAds.Initialize((initStatus) =>
        {
            // SDK initialization is complete
        });
        ...
    }
}

Warning: If you forgot to initialize the Mobile Ads SDK, or use the deprecated MobileAds.Initialize(string appID) API, the ad placement's auto-load feature will not work.

Creating ad placements

The first step in displaying a banner with Google Mobile Ads is to create and configure an ad placement. You can select an ad placement of Banner, Interstitial, or Rewarded format from Assets > Google Mobile Ads > Ad Placements in the Unity Editor. Three demo ad placements are then set up and ready for use.

To add a new Ad Placement, click the Add New Placement button at the end of the list. You can configure the ad placement from the Inspector view.

Note: You can send feedback about the Unity plugin and the ad placements feature using the Send Feedback button.

Ad placement configuration

Each placement has the following properties:

Placement Name

Name of the placement. Used to identify placements when setting up ads in a scene.

Ad Format

Banner, Rewarded, Interstitial. Type of the ad.

Ad unit ID

Provide your banner ad unit ID for Android and iOS. You need to provide at least one ad unit ID.

Persistent across scenes

When checked, the banner will persist on the screen regardless of scene changes (same behavior as DontDestroyOnLoad).

Auto Load Enabled

When checked, an ad will be loaded automatically when a scene associated with the ad placement is loaded.

The following screenshot shows an example of an Ad Placement named My Awesome Banner.

Adding an AdGameObject to the scene

You can add an AdGameObject for Banner, Interstitial, or Rewarded formats to your scene using GameObject > Google Mobile Ads in the Unity Editor. Select the format to add a placement to the active scene.

Once you've added an AdGameObject to the scene, you'll see a GameObject representing the ad in the Hierarchy view of the Unity Editor.

Key Point: An AdGameObject does not have any rendered components. Therefore, you can place the GameObject anywhere in the scene.

You can change the name of the placement by changing the name of the GameObject itself. The following screenshot shows an example of an AdGameObject named Banner Ad.

Warning: Do not use an existing AdGameObject name. Doing so will cause a runtime exception. Each AdGameObject name must be unique.

AdGameObject settings

You can configure the AdGameObject in your scene from the Inspector view in the settings for the Ad Game Object (Script) component.

Ad Placement

Select the ad placement from the drop-down list of configured placements. The list will only have ad units for the right format. For example, for banner ad game objects the dropdown will show only configured banner ad placements.

BannerAdGameObject configuration (banner only)

• Size - Select the size of the banner that you want to use.
  • Anchored Adaptive Banner provides a few more options:
    • Orientation - Select device orientation used to calculate the ad height.
    • Use full screen width - When checked, the banner will occupy full screen width. You can adjust % width of the screen (50~99%) if you uncheck the Use full screen width option.
  • Custom allows you to provide the banner width and height.
• Ad Position - Select the position where the banner should be placed.

Callbacks

You can implement functions that correspond to ad callbacks. For example, if you want to handle when a banner ad fails to load:

1. Create a function compatible with the ad callback.

   public void OnBannerAdFailedToLoad(string reason) {
       Debug.Log("Banner ad failed to load: " + reason);
   }
   

2. Attach the script which contains the above function to any GameObject in the scene.

3. Click the + button, then drag & drop the GameObject that you've attached the script to.

   

4. Select the function that you want to link to the ad callback. For the parameterized ad callbacks, select the function to accept the dynamic variable so you can get the parameter value from the SDK.

   

Use AdGameObject from script

Get the AdGameObject instance from the script

All AdGameObject objects have the convenience method LoadAd(). This will load an ad with a plain, untargeted AdRequest. To apply targeting, you should use LoadAd(AdRequest adRequest) using your own configured ad request.

To get the instance of an AdGameObject use the following method for each format:

Banner

MobileAds.Instance.GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

The returned BannerAdGameObject object also has convenience methods Hide() and Show().

Interstitial

MobileAds.Instance.GetAd<InterstitialAdGameObject>("AD_GAMEOBJECT_NAME");

The returned InterstitialAdGameObject object has a convenience method ShowIfLoaded().

Rewarded

MobileAds.Instance.GetAd<RewardedAdGameObject>("AD_GAMEOBJECT_NAME");

The returned RewardedAdGameObject object has a convenience method ShowIfLoaded().

For example, you can get an instance of a BannerAdGameObject and load it as follows:

using UnityEngine;

using GoogleMobileAds.Api;
using GoogleMobileAds.Placement;

public class BannerTestScript : MonoBehaviour
{
    BannerAdGameObject bannerAd;

    void Start()
    {
        bannerAd = MobileAds.Instance
            .GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

        bannerAd.LoadAd();
        ...
    }
    ...
}

If there is a BannerAdGameObject named BannerAd, you can get an instance of it like this:

MobileAds.Instance.GetAd<BannerAdGameObject>("BannerAd");

Access underlying ad object in AdGameObject

These snippets demonstrate how to access the underlying ad object associated with the AdGameObject.

Banner

BannerAdGameObject bannerAd = MobileAds.Instance
    .GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

// Access BannerView object
BannerView bannerView = bannerAd.BannerView;

Interstitial

InterstitialAdGameObject interstitialAdGameObject = MobileAds.Instance
    .GetAd<InterstitialAdGameObject>("AD_GAMEOBJECT_NAME");

// Access InterstitialAd object
InterstitialAd interstitialAd = interstitialAdGameObject.InterstitialAd;

Rewarded

RewardedAdGameObject rewardedAdGameObject = MobileAds.Instance
    .Get<RewardedAdGameObject>("AD_GAMEOBJECT_NAME");

// Access RewardedAd object
RewardedAd rewardedAd = rewardedAdGameObject.RewardedAd;

Examples

Show an interstitial ad

Here is an example of how to configure a game to load and show an interstitial ad using an AdGameObject.

Add an InterstitialAdGameObject to the scene and turn on the Auto Load Enabled feature, so that the ad is loaded automatically when the scene loads.

Next, make sure you've initialized the SDK using as follows. Note that the Auto Load feature in AdGameObject will not work if you forget to initialize the SDK.

Then display an interstitial ad between a screen transition by calling the InterstitialAdGameObject.ShowIfLoaded() function. The following code shows an example of displaying an interstitial ad between a scene transition.

using UnityEngine;
using UnityEngine.SceneManagement;

using GoogleMobileAds.Api;
using GoogleMobileAds.Placement;

public class MainScene : MonoBehaviour
{
    InterstitialAdGameObject interstitialAd;

    void Start()
    {
        interstitialAd = MobileAds.Instance
            .GetAd<InterstitialAdGameObject>("interstitial");

        MobileAds.Initialize((initStatus) => {
            Debug.Log("Initialized MobileAds");
        });
    }

    public void OnClickShowGameSceneButton()
    {
        // Display an interstitial ad
        interstitialAd.ShowIfLoaded();

        // Load a scene named "GameScene"
        SceneManager.LoadScene("GameScene");
    }
}

Since you've enabled the Auto Load feature in the ad placement, you don't need to request an ad explicitly. When the scene changes, an interstitial ad will appear if one is ready.

If you want to manually request an ad, disable the Auto Load feature from the ad placements inspector and call the InterstitialAdGameObject.LoadAd() function instead. The following code snippet shows how to manually request an ad.

public class MainScene : MonoBehaviour
{
    InterstitialAdGameObject interstitialAd;

    void Start()
    {
        interstitialAd = MobileAds.Instance
            .GetAdGameObject<InterstitialAdGameObject>("interstitial");

        MobileAds.Initialize((initStatus) => {
            Debug.Log("MobileAds initialized");

            // Load an interstitial ad after the SDK initialization is complete
            interstitialAd.LoadAd();
        });
    }
    ...
}

Handle "watch a rewarded ad" button state

Here is an example of how to enable a "watch a rewarded ad" button by using ad placements.

Add a Button GameObject (named Button in this example) to the scene, which will be used to display a rewarded ad. We'll make this button available only when a rewarded ad is available.

In the Start() method, change the active state of the Button to false. This will make the button disappear from the scene.

public class MainScene : MonoBehaviour
{
    ...
    void Start()
    {
        GameObject.Find("Button").SetActive(false);
        ...
    }
}

Add a RewardedAdGameObject to the scene and select the AdMob Demo Rewarded Ad Ad Placement from the dropdown.

Key Point: Make sure you have selected Auto Load Enabled in the Placement Configuration (Assets > Google Mobile Ads > Ad Placements).

Under the Callbacks section in the RewardedAdGameObject inspector, click the + button from On Ad Loaded() to enable the function to be called when a rewarded ad is loaded.

Drag and drop the Button GameObject that you added in the previous step to the None (Object) field. Select a function to be called from the dropdown. Click No Function > GameObject > SetActive(bool), then click the checkbox so it sends true as a parameter (calls SetActive(true)).

In this Callbacks section, you can also link up an event that will be called when the RewardedAd.OnUserEarnedReward event is fired. For more details, refer to this section.

Next, make the button to display a rewarded ad when clicked. From the On Click() Callbacks section in the button inspector, click the + button and drag and drop the Rewarded Ad Placement GameObject (named Rewarded Ad in this example) to the None (Object) field.

Then, attach the RewardedAdGameObject.ShowIfLoaded() function to the button's On Click() callback.

Lastly, don't forget to initialize the SDK. The following code snippet is the complete code for the scene used in this example:

using UnityEngine;

using GoogleMobileAds.Api;

public class MainScene : MonoBehaviour
{
    void Start()
    {
        GameObject.Find("Button").SetActive(false);

        MobileAds.Initialize((initStatus) => {
            Debug.Log("Initialized MobileAds");
        });
    }
}

Once you run the project, you'll see the button displayed on the scene when a rewarded ad is loaded and ready to be shown.

Configure a reward callback for a RewardedAdGameObject

Here is an example of how to configure a rewarded callback to a rewarded ad placement, so you can give a reward to a user when a callback function is called.

Create a new script and define a function which accepts Reward as a parameter as follows.

using UnityEngine;
using GoogleMobileAds.Api;

class RewardedTestScript : MonoBehaviour {
    ...
    public void OnUserEarnedReward(Reward reward) {
        Debug.Log("OnUserEarnedReward: reward=" +
            reward.Type + ", amount=" + reward.Amount);
    }
    ...
}

Attach the RewardedTestScript script to any GameObject (except the Ad Placement GameObject) in the scene. In this example, it is attached to the Main Camera GameObject.

Add a RewardedAdGameObject to the scene. Then, under the Callbacks section in the RewardedAdGameObject inspector, click the + button on On User Earned Reward (Reward) to enable the function to be called when a reward is granted to a user.

Drag and drop the Main Camera GameObject that you've added in the previous step to the None (Object) field. Select a function to be called from the dropdown. Click No Function > RewardedTestScript > OnUserEarnedReward.

Once you run the project and watch a rewarded ad, RewardedTestScript.OnUserEarnedReward() will be invoked when you are to be rewarded for interacting with the ad.