[Video](https://www.youtube.com/watch?v=Dww_pS4wmnU)

> [!WARNING]
> **Warning:** Google Mobile Ads Unity Plugin Unity plugin's Ad Placements feature is deprecated. There are no plans to move it into the public release.

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](https://developers.google.com/admob/unity/quick-start.md.txt#prerequisites).

- [Download](https://dl.google.com/googleadmobadssdk/GoogleMobileAds-Ad-Placements.unitypackage)
  and import the early build of GMA Unity plugin.

- [Set your AdMob app ID](https://developers.google.com/admob/unity/quick-start.md.txt#set_up_app_id) in the
  Unity Editor.

## Initialize Google Mobile Ads Unity Plugin

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

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

> [!WARNING]
> **Warning:** If you forgot to initialize Google Mobile Ads Unity Plugin, 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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of0.png)
![](https://developers.google.com/static/admob/images/ad-placements/Copy-of1.png)

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]
> **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`](https://docs.unity3d.com/ScriptReference/Object.DontDestroyOnLoad.html)).

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**.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of2.png)

## 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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of3.png)

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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of4.png)

> [!IMPORTANT]
> **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**.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of5.png)

> [!WARNING]
> **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.

    ![](https://developers.google.com/static/admob/images/ad-placements/Copy-of6.png)

`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.

   ```c#
   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.

   ![](https://developers.google.com/static/admob/images/ad-placements/Copy-of7.png)
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.

   ![](https://developers.google.com/static/admob/images/ad-placements/Copy-of8.png)

## 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

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

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

### Interstitial

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

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

### Rewarded

```c#
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:

```c#
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:

```c#
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

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

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

### Interstitial

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

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

### Rewarded

```c#
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.

```c#
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.

```c#
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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of10.png)

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

```c#
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.

> [!IMPORTANT]
> **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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of11.png)

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)`).

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of12.png)

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](https://developers.google.com/admob/unity/ad-placements.md.txt#reward_callback).

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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of13.png)

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

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of14.png)

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

```c#
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.

```c#
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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of15.png)

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.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of16.png)

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**.

![](https://developers.google.com/static/admob/images/ad-placements/Copy-of17.png)

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.