Get Started

If you're using the Unity game engine, there is an officially supported plugin that enables you to serve banner and interstitial ads to iOS and Android by writing scripts in the Unity development environment.

Download the plugin View source code

Requirements

• Unity 4 or higher
• To deploy on iOS
  • Xcode 6 or higher
  • Google Mobile Ads SDK 7.7.0 or higher
• To deploy on Android:
  • Android SDK 3.2 or higher
  • Google Play services 7.5 or higher

Import the plugin into your game

1. Open your project in the Unity editor. Select Assets > Import Package > Custom Package and find the GoogleMobileAdsPlugin.unitypackage file you downloaded.

   

2. Make sure all of the files are selected and click Import.

   

Run your project

1. If you are running Unity 4 you need to make the following changes:

   iOS

   Modify the following build settings within the Xcode project exported by Unity:

   • Set Enable Modules (C and Objective-C) to Yes in Build Settings.
   • Add $(inherited) to Other Linker Flags in Build Settings.

   Android

   Set the unityplayer.ForwardNativeEventsToDalvik tag to true in your main Unity activity to ensure that ads are clickable (highlighted below):

   
   <activity android:name="com.unity3d.player.UnityPlayerNativeActivity"
       android:label="@string/app_name">
       <intent-filter>
         <action android:name="android.intent.action.MAIN" />
         <category android:name="android.intent.category.LAUNCHER" />
       </intent-filter>
       <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
       <meta-data android:name="unityplayer.ForwardNativeEventsToDalvik"
           android:value="true" />
   </activity>
       

2. Import the Google Mobile Ads SDK into your project.

   iOS

   1. Navigate to File > Build Settings, select the iOS platform, and choose Build to export an Xcode project and a corresponding CocoaPods xcworkspace.
   2. Open up the exported xcworkspace and navigate to Product > Run in Xcode to run your project.

   You've just imported the plugin for iOS!

   Android

   Navigate to File > Build Settings, select the Android platform, then choose Build And Run.

   

   You've just imported the plugin for Android!

Once these steps are complete, see the Unity plugin API section for more information on how to request banner and interstitial ads using the plugin.

Unity plugin API

You can use the common C# API in the Google Mobile Ads plugin to request banner and interstitial ads. The code can be written once and deployed to both Android and iOS.

Basic banner request

Here's the minimal code needed to create and load a banner ad:

using GoogleMobileAds.Api;
…
private void RequestBanner()
{
    #if UNITY_EDITOR
        string adUnitId = "unused";
    #elif UNITY_ANDROID
        string adUnitId = "INSERT_ANDROID_BANNER_AD_UNIT_ID_HERE";
    #elif UNITY_IPHONE
        string adUnitId = "INSERT_IOS_BANNER_AD_UNIT_ID_HERE";
    #else
        string adUnitId = "unexpected_platform";
    #endif

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

The AdPosition enum specifies where to place the banner.

Note how different ad units are used, depending on the platform. When using AdMob in particular, 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.

Basic interstitial request

Here's the minimal code needed to load an interstitial ad:

using GoogleMobileAds.Api;
…
private void RequestInterstitial()
{
    #if UNITY_ANDROID
        string adUnitId = "INSERT_ANDROID_INTERSTITIAL_AD_UNIT_ID_HERE";
    #elif UNITY_IPHONE
        string adUnitId = "INSERT_IOS_INTERSTITIAL_AD_UNIT_ID_HERE";
    #else
        string adUnitId = "unexpected_platform";
    #endif

    // Initialize an InterstitialAd.
    InterstitialAd interstitial = new InterstitialAd(adUnitId);
    // Create an empty ad request.
    AdRequest request = new AdRequest.Builder().Build();
    // Load the interstitial with the request.
    interstitial.LoadAd(request);
}

Unlike banner ads, interstitial ads must be explicitly shown. At an appropriate stopping point in your game, such as when the current level ends, check that the interstitial is ready before showing it. A good place to show an interstitial is when the game is over:

private void GameOver()
{
  if (interstitial.IsLoaded()) {
    interstitial.Show();
  }
}

Custom ad sizes

Instead of using an AdSize constant, you can specify a custom size for your ad:

AdSize adSize = new AdSize(250, 250);
BannerView bannerView = new BannerView(adUnitId, adSize, AdPosition.Bottom);

Test ads

During development, it is recommended to request test ads to avoid generating false impressions. To request test ads, add your encrypted device ID to the AddTestDevice() method when building the ad request. This ID can only be found in the logs on both Android and iOS when running your apps and making a live request.

Here's how to include test devices when building an ad request:

AdRequest request = new AdRequest.Builder()
    .AddTestDevice(AdRequest.TestDeviceSimulator)       // Simulator.
    .AddTestDevice("2077ef9a63d2b398840261c8221a0c9b")  // My test device.
    .Build();

Ad request targeting

To provide additional targeting to ad requests, set these targeting parameters when building a request. This sample ad request shows what targeting methods are available:

AdRequest request = new AdRequest.Builder()
    .SetGender(Gender.Male)
    .SetBirthday(new DateTime(1985, 1, 1))
    .TagForChildDirectedTreatment(true)
    .AddExtra("excl_cat", "cars,sports") // Category exclusions for DFP.
    .Build();

Ad events

Both BannerView and InterstitialAd contain the same ad events that you can register for. These events are of type EventHandler. This example demonstrates setting ad events on a banner:

private void RequestBanner()
{
    BannerView bannerView = new BannerView(adUnitId, AdSize.Banner, AdPosition.Top);
    // Called when an ad request has successfully loaded.
    bannerView.OnAdLoaded += HandleOnAdLoaded;
    // Called when an ad request failed to load.
    bannerView.OnAdFailedToLoad += HandleOnAdFailedToLoad;
    // Called when an ad is clicked.
    bannerView.OnAdOpened += HandleOnAdOpened;
    // Called when the user returned from the app after an ad click.
    bannerView.OnAdClosed += HandleOnAdClosed;
    // Called when the ad click caused the user to leave the application.
    bannerView.OnAdLeavingApplication += HandleOnAdLeavingApplication;
}

public void HandleOnAdLoaded(object sender, EventArgs args)
{
    print("OnAdLoaded event received.");
    // Handle the ad loaded event.
}

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)
{
  print("Interstitial Failed to load: " + args.Message);
  // Handle the ad failed to load event.
};

You only need to register for the events you care about.

Hide and show banners

By default, banners are visible. To temporarily hide a banner, call the following:

bannerView.Hide();

To show it again, call the following:

bannerView.Show();

Clean up banner and interstitial ads

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

bannerView.Destroy();
interstitial.Destroy();

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

AdMob mediation support

To perform mediation with the Unity plugin, you must download and include both the SDK and adapter libraries for each third-party network.