Integrating Unity Ads into Your Game

In this tutorial, you’ll learn the following as you integrate Unity Ads into your game:

• How to sign up for and add the Unity Ads service.
• How to display simple video ads in your game
• How to design and display reward-linked video ads
• How to leverage Unity Ads features such as filtering and device orientation

You’ll take an existing 2D Space Lander starter project and add in some Unity Ads. By the end, you’ll have a game that demonstrates how to reward players in-game for watching video ads.

Getting Started

Make sure you have the latest version of Unity; this tutorial was written for version 5.3.4. Download the starter project for this tutorial here. Extract and open the IntegratingUnityAdsStarter project in Unity. Don’t worry if you get a warning that the project was opened in an older version of Unity, simply click OK to upgrade.

Don’t worry if you see a script error. This will disappear once your project is set up for the ad service.

The Lander Scene

Open the Lander scene under the Scenes sub-folder. You should see the main game scene, all set up and waiting for you to apply the magic of Unity Ads.

Unity Ads requires that the build platform to be set to either iOS or Android. To follow along with this tutorial, you need to switch the active build platform to one of those two platforms.

From the main menu:

• Select File / Build Settings.
• Select either iOS or Android.
• Click Switch Platform.

The screenshot below shows Android as the build platform.

Switch your game view window to use a portrait aspect ratio, as this game is designed to run in portrait mode.

Setup the Ads Service

Open the Services tab in the editor. You can usually find the tab above the Inspector panel. If not, select Window / Services from the main menu.

Here’s what you should see:

You’ll now link the project to your own Unity organization.

• Click New Link.
• Select your organization name in the drop-down.
• Click Create.

Now to create a Unity Project ID for the game under your organization name.

• Click the toggle on the top right to enable Unity Ads.
• Ensure the slider is in the on position.
• Choose the appropriate Designation for Apps Directed to Children option.
• Click Save Changes.

Expand the Advanced Settings section on the Unity Ads Services tab. Note the two game IDs created for your game. These are used when Unity Ads initializes within the game, and are specific to the mobile platform the game is running on.

The Unity Ads Dashboard

In the Unity Editor Services window, click Go to Dashboard. This will open your web browser and sign you into your Unity Services dashboard. Where you end up depends on how long ago you created your account. You’ll either go to the Unity Ads or the Unity Services dashboard. If you end up on the services dashboard, just click the link for Unity Ads.

You should see your project listed on your Unity Ads Dashboard page.

Initializing Unity Ads

You will be starting things off nice and easy. You’ll check that Unity Ads initialize and display debug information on game start up.

An AdManager.cs script already exists in the starter project. Navigate to the Scripts folder and load it into your code editor.

Add the following debug code to Start() in AdManager.cs:

Debug.Log("Unity Ads initialized: " + Advertisement.isInitialized);
Debug.Log("Unity Ads is supported: " + Advertisement.isSupported);
Debug.Log("Unity Ads test mode enabled: " + Advertisement.testMode);

This lets you check that the Ads service initializes properly. The debug info will display in the console when the game starts.

Save the script and run the game. You should see that the service initializes, there is support for ads and that test mode is enabled.

Adding Video Ads to your Game

What better way to get to the meat of Unity Ads than to tackle some code?

You will now design an ad manager class which will use the Singleton pattern to keep things simple. You will extend the AdManager class that is already in place to let you check that ads are ready. Then it will display the ads and issue rewards for players who finish watching the ad using callback methods.

The Game Over UI

Start the game and fly around until you crash into a rock. You’ll see the game over UI appear with some buttons that offer different ad options. You’ll hook these buttons up to some code in just a bit. For example, notice that the Watch a video ad button does nothing.

Time to make that button display a Unity video ad!

Open AdManager.cs in your code editor and add the following method to the class:

public void ShowStandardVideoAd() {
  ShowVideoAd();
}

This method returns void so that you can attach it to a button action. That button action will call ShowVideoAd() with no callback and no zone ID to play a standard video ad with the default ad callback handler.

Still working in AdManager.cs, add the following method to the class:

public void ShowVideoAd(Action<ShowResult> adCallBackAction = null, string zone = "") {
  
  StartCoroutine(WaitForAdEditor());

  if (string.IsNullOrEmpty(zone)) {
      zone = null;
  }
  
  var options = new ShowOptions();

  if (adCallBackAction == null) {
      options.resultCallback = DefaultAdCallBackHandler;
  } else {
      options.resultCallback = adCallBackAction;
  }
    
  if (Advertisement.IsReady(zone)) {
      Debug.Log("Showing ad for zone: " + zone);
      Advertisement.Show(zone, options);
  } else {
      Debug.LogWarning("Ad was not ready. Zone: " + zone);
  }
}

StartCoroutine is a trick to pause the game when running in the editor. It does this by setting the timescale to 0f. When running on an actual device, Unity Ads will pause the game for you, so this method will do nothing in the editor.

You then check to see if an empty string was passed in as the zone ID. If so, set zone is set to null, which causes Unity Ads to display a standard, non-rewarded video ad.

Next a check happens to see if a valid ad callback action was passed in or not. If so, you set the result callback handler to use the callback action you specified. Otherwise a default callback handler assignment takes place.

Finally you check that an ad was preloaded in the background and whether it is ready to play. If ready, the ad launches. The zone and options for callback handling are also passed in here. When the ad is finished playing, was skipped, or fails, a callback method executes depending on the circumstance.

Here’s the final method to add to AdManager.cs:

private void DefaultAdCallBackHandler(ShowResult result) {
  switch (result) {
    case ShowResult.Finished:
      Time.timeScale = 1f;
      break;

    case ShowResult.Failed:
      Time.timeScale = 1f;
      break;

    case ShowResult.Skipped:
      Time.timeScale = 1f;
      break;
  }
}

This switch statement is the default ad callback handler. It runs code based on whether the video ad displayed finished, failed, or was skipped.