Native Ads Express

The native express ad format is being discontinued. Starting October 23, 2017, you'll no longer be able to create new native express ad units. Existing native express ad units will stop serving ads on March 1, 2018.

Native Express ads are similar to banners in that they're rectangular ads that you can drop into a layout and size how you like. The key difference is that you can control the ad's presentation details (things like image sizes, fonts, colors, and so on) by uploading a CSS template for your ad unit. AdMob combines that template with advertiser assets (such as icons, images, and text) and displays the result in a NativeExpressAdView. This approach minimizes the amount of code needed for Native Ads Express, while helping you display ads that look natural in your app.

This guide shows you how to integrate Native Ads Express from AdMob into a Unity app. In addition to code snippets and instructions, it includes information about how to choose the correct size category for your ad units.

Prerequisites

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

Create a NativeExpressAdView

The first step toward displaying a native express ad is to create a NativeExpressAdView object in a script attached to a GameObject.

 ...
using GoogleMobileAds.Api;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{

    private void RequestNativeExpressAdView()
    {
        #if UNITY_ANDROID
            string adUnitId = "ca-app-pub-3940256099942544/2177258514";
        #elif UNITY_IPHONE
            string adUnitId = "ca-app-pub-3940256099942544/2562852117";
        #else
            string adUnitId = "unexpected_platform";
        #endif

        // Creates a 320x150 native express ad at the top of the screen.
        NativeExpressAdView nativeExpressAdView = new NativeExpressAdView(adUnitId,
                                          new AdSize(320, 150), AdPosition.Top);
    }
}

The constructor for a NativeExpressAdView has the following parameters:

  • adUnitID - The AdMob ad unit ID from which the NativeExpressAdView should load ads.
  • AdSize - The AdMob ad size you'd like to use (see the Choose a size section below for details).
  • AdPosition - The position where the native express ad should be placed. The AdPosition enum lists the valid ad position values.

It is important to note how different ad units are used, depending on the platform. You'll need to use an iOS ad unit for making ad requests on iOS and an Android ad unit for making requests on Android.

Choose a size

Rather than forcing publishers to choose among fixed sizes, Native Ads Express offers several template sizes (chosen when creating an ad unit), each with a range of height and width values in device-independent pixels (dp):

Template size Min width Max width Min height Max height
Small 280 1200 80 612
Medium 280 1200 132 1200
Large 280 1200 250 1200

A publisher who wants to display a "Medium" template size can use widths between 280 and 1200 dp, and heights from 132 to 1200 dp. That means that 300 by 200, 450 by 150, and 613 by 572 are all valid for the Medium template size. Bear in mind, though, that not all sizes are likely to make for a good presentation. While it's technically possible to request a "Small" template with a size of 1200 by 80, it's probably not the best choice. Also, be sure to consider the screen dimensions of the device on which you're displaying the ad. Larger sizes should generally be reserved for presentation on tablets.

In the event that an app makes a request with an ad size that falls outside the range for the ad unit's template, an error is returned.

Publishers can also use the AdSize.FullWidth constant when creating an AdSize for a NativeExpressAdView. In this case, the ad occupies the entire width of the device screen.

Custom ad position

For greater control over where a NativeExpressAdView is placed on screen than what is offered by AdPosition values, use the constructor for NativeExpressAdView that has x- and y-coordinates as parameters:

// Create a 320x150 native express ad at coordinate (0,50) on screen.
NativeExpressAdView nativeExpressAdView =
   new NativeExpressAdView(adUnitId, new AdSize(320, 150), 0, 50);

The top-left corner of the NativeExpressAdView will be positioned at the x and y values passed to the constructor.

Always test with test ads

The sample code above contains an ad unit ID and you're free to request ads with it. It's been specially configured to return test ads rather than production ads for every request, which makes it safe to use.

However, once you register an app in the AdMob UI and create your own ad unit IDs for use in your app, you'll need to explicitly configure your device as a test device when you're developing. This is extremely important. Testing with real ads (even if you never tap on them) is against AdMob policy and can cause your account to be suspended. See Test Ads for information on how you can make sure you always get test ads when developing.

Load an ad

Once the NativeExpressAdView is instantiated, the next step is to load an ad. That's done with the loadAd() method in the NativeExpressAdView class. It takes an AdRequest argument, which holds runtime information (such as targeting info) about a single ad request.

Here's an example that shows how to load an ad:

...
using GoogleMobileAds.Api;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private NativeExpressAdView nativeExpressAdView;
    …

    public void Start()
    {
        this.RequestNativeExpressAdView();
    }

    private void RequestNativeExpressAdView()
    {
        #if UNITY_ANDROID
            string adUnitId = "ca-app-pub-3940256099942544/2177258514";
        #elif UNITY_IPHONE
            string adUnitId = "ca-app-pub-3940256099942544/2562852117";
        #else
            string adUnitId = "unexpected_platform";
        #endif

        // Create a 320x50 native express ad at the top of the screen.
        nativeExpressAdView = new NativeExpressAdView(adUnitId, AdSize.Banner,
                                                      AdPosition.Top);
        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the native express ad with the request.
        nativeExpressAdView.LoadAd(request);
    }
}

That's it! Your app is now ready to display native express ads from AdMob.

Ad events

To further customize the behavior of your ad, you can hook into a number of events in the ad's lifecycle: loading, opening, closing, and so on. You can listen for these events by registering a delegate for the appropriate EventHandler, as shown below.

...
using GoogleMobileAds.Api;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private NativeExpressAdView nativeExpressAdView;
    …

    public void Start()
    {
        this.RequestNativeExpressAdView();
    }

    private void RequestNativeExpressAdView()
    {
        #if UNITY_ANDROID
            string adUnitId = "ca-app-pub-3940256099942544/2177258514";
        #elif UNITY_IPHONE
            string adUnitId = "ca-app-pub-3940256099942544/2562852117";
        #else
            string adUnitId = "unexpected_platform";
        #endif

        // Create a 320x150 native express ad at the top of the screen.
        nativeExpressAdView = new NativeExpressAdView(adUnitId,
                                        new AdSize(320, 150), AdPosition.Top);

        // Called when an ad request has successfully loaded.
        nativeExpressAdView.OnAdLoaded += HandleOnAdLoaded;
        // Called when an ad request failed to load.
        nativeExpressAdView.OnAdFailedToLoad += HandleOnFailedToLoad;
        // Called when an ad is clicked.
        nativeExpressAdView.OnAdOpening += HandleOnAdOpened;
        // Called when the user returned from the app after an ad click.
        nativeExpressAdView.OnAdClosed += HandleOnAdClosed;
        // Called when the ad click caused the user to leave the application.
        nativeExpressAdView.OnAdLeavingApplication += HandleOnAdLeftApplication;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the native express ad with the request.
        nativeExpressAdView.LoadAd(request);
    }

    public void HandleAdLoaded(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleAdLoaded event received");
    }

    public void HandleAdFailedToLoad(object sender, AdFailedToLoadEventArgs args)
    {
        MonoBehaviour.print("HandleFailedToReceiveAd event received with message: "
                            + args.Message);
    }

    public void HandleAdOpened(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleAdOpened event received");
    }

    public void HandleAdClosed(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleAdClosed event received");
    }

    public void HandleAdLeftApplication(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleAdLeftApplication event received");
    }
}

The OnAdFailedToLoad event contains special event arguments. It passes an instance of HandleAdFailedToLoadEventArgs with a Message describing the error:

public void HandleOnAdFailedToLoad(object sender, AdFailedToLoadEventArgs args)
{
  MonoBehavior.print("Ad failed to load: " + args.Message);
  // Handle the ad failed to load event.
};
Ad eventDescription
OnAdLoaded The OnAdLoaded event is executed when an ad has finished loading.
OnAdFailedToLoad The OnAdFailedToLoad event is invoked when an ad fails to load. The Message parameter describes the type of failure that occurred.
OnAdOpened This method is invoked when the user taps on an ad. If you're using an analytics package to track clickthroughs, this is a good place to record one.
OnAdClosed When a user returns to the app after viewing an ad's destination URL, this method is invoked. Your app can use it to resume suspended activities or perform any other work necessary to make itself ready for interaction.
OnAdLeavingApplication This method is invoked after onAdOpened, when a user click opens another app (such as the Google Play store), backgrounding the current app.

Clean up Native Express ads

When you are finished with a NativeExpressAdView, make sure to call the Destroy() method before dropping your reference to it:

nativeExpressAdView.Destroy();

This notifies the plugin that the object is no longer used and the memory it occupied can be reclaimed. Failure to call this method results in memory leaks.

Additional resources

Samples

Next steps

Send feedback about...

AdMob for Unity
AdMob for Unity
Need help? Visit our support page.