Knowledge base

Integration Guide for Unity

This guide covers both methods for integrating Unity Ads in the Unity engine:

  • Services Window integration
  • Asset Package integration

Contents

  • Setting build targets
  • Enabling the Ads Service
    • Services Window method
    • Asset Package method
  • Showing an ad
  • Rewarding players for watching ads
    • Example rewarded ads button code
  • Managing Settings in the Ads Dashboard

Setting build targets

Configure your project for a supported platform using the Build Settings window.

Set the platform to iOS or Android, then click Switch Platform.

The Build Settings window

Enabling the Ads Service

This process varies slightly depending on your integration preference; the Services Window method or the Asset Package method.

Services Window method

To enable Ads, you need to configure your project for Unity Services. This requires setting an Organization and Project Name. See documentation on setting up Services.

With Services set up, you can enable Unity Ads:

  1. In the Unity Editor, select Window > Services to open the Services window.
  2. Select Ads from the Services window menu.
  3. Click the toggle to the right to enable the Ads Service (see image below).
  4. Specify whether your product targets children under 13, by clicking in the checkbox then click Continue.

Services Window

Asset Package method

Before integrating Ads the Asset Package, you need to create a Unity Ads Game ID, as described below.

Create a Unity Ads Game ID

  1. In your web browser, navigate to the Unity Ads Dashboard, using your Unity Developer Network UDN Account, and select Add new project.

    Add a new project

  2. Select applicable platforms (iOS, Android, or both).

    Select your platform

  3. Locate the platform-specific Game ID and copy it for later.

    Locate your Game ID

Integrate Ads to the Asset Package

  1. Declare the Unity Ads namespace, UnityEngine.Advertisements in the header of your script (see UnityEngine.Advertisements documentation):

         using UnityEngine.Advertisements;
    
  2. Inititalize Unity Ads in your script using the copied Game ID string, gameId:

         Advertisement.Initialize(string gameId)
    

Note: The initialization call typically goes in the Start() function of your code.

Showing ads

Note: Unity Ads is available from the Services Window in Unity 5.2 or later.

With the Service enabled, you can implement the code in any script to display ads.

  1. Declare the Unity Ads namespace, UnityEngine.Advertisement in the header of your script (see UnityEngine.Advertisements documentation):

    using UnityEngine.Advertisements;
    
  2. Call the Show() function to display an ad:

     Advertisement.Show()
    

Rewarding players for watching ads

Rewarding players for watching ads increases user engagement, resulting in higher revenue. For example, games may reward players with in-game currency, consumables, additional lives, or experience-multipliers.

To reward players for completing a video ad, use the HandleShowResult callback method in the example below. Be sure to check that the result is equal to ShowResult.Finished, to verify that the user hasn't skipped the ad.

  1. In your script, add a callback method.
  2. Pass the method as a parameter when when calling Show().
  3. Call Show() with the "rewardedVideo" placement to make the video unskippable.

Note: See Unity Ads documentation for more detailed information on placements.

void ShowRewardedVideo ()
{
    ShowOptions options = new ShowOptions();
    options.resultCallback = HandleShowResult;

    Advertisement.Show("rewardedVideo", options);
}

void HandleShowResult (ShowResult result)
{
    if(result == ShowResult.Finished) {
        Debug.Log("Video completed - Offer a reward to the player");

    }else if(result == ShowResult.Skipped) {
        Debug.LogWarning("Video was skipped - Do NOT reward the player");

    }else if(result == ShowResult.Failed) {
        Debug.LogError("Video failed to show");
    }
}

Example rewarded ads button code

Use the code below to create a rewarded ads button. The ads button displays an ad when pressed as long as ads are available.

  1. Select Game Object > UI > Button to add a button to your Scene.
  2. Select the button you added to your Scene, then add a script component to it using the Inspector. (In the Inspector, select Add Component > New Script .)
  3. Open the script and add the following code:

    Note: The two sections of code that are specific to Asset Package integration are called out in comments.
 using UnityEngine;
using UnityEngine.UI;
using UnityEngine.Advertisements;

//---------- ONLY NECESSARY FOR ASSET PACKAGE INTEGRATION: ----------//

#if UNITY_IOS
private string gameId = "1486551";
#elif UNITY_ANDROID
private string gameId = "1486550";
#endif

//-------------------------------------------------------------------//

ColorBlock newColorBlock = new ColorBlock();
public Color green = new Color(0.1F, 0.8F, 0.1F, 1.0F);

[RequireComponent(typeof(Button))]
public class UnityAdsButton : MonoBehaviour
{
    Button m_Button;

    public string placementId = "rewardedVideo";

    void Start ()
    {    
        m_Button = GetComponent<Button>();
        if (m_Button) m_Button.onClick.AddListener(ShowAd);

        if (Advertisement.isSupported) {
            Advertisement.Initialize (gameId, true);
        }

        //---------- ONLY NECESSARY FOR ASSET PACKAGE INTEGRATION: ----------//

        if (Advertisement.isSupported) {
            Advertisement.Initialize (gameId, true);
        }

        //-------------------------------------------------------------------//

    }

    void Update ()
    {
        if (m_Button) m_Button.interactable = Advertisement.IsReady(placementId);
    }

    void ShowAd ()
    {
        ShowOptions options = new ShowOptions();
        options.resultCallback = HandleShowResult;

        Advertisement.Show(placementId, options);
    }

    void HandleShowResult (ShowResult result)
    {
        if(result == ShowResult.Finished) {
        Debug.Log("Video completed - Offer a reward to the player");

        }else if(result == ShowResult.Skipped) {
            Debug.LogWarning("Video was skipped - Do NOT reward the player");

        }else if(result == ShowResult.Failed) {
            Debug.LogError("Video failed to show");
        }
    }
}
  1. Press Play in the Unity Editor to test the Ads button integration.

For further guidance, see the Unity Ads forum.


Managing settings in the Ads Dashboard

Use settings to modify placements and other game-specific settings in your project. (See Unity Ads documentation for further information on placements.)

  1. In your web browser, navigate to the Unity Ads Dashboard, using your Unity Developer Network UDN Account, and locate the project for your game.

    Unity Ads Dashboard with project selection highlighted

  2. Select an applicable platform (iOS or Android).

    Unity Ads Dashboard with platform selection highlighted

  3. Select placement. (See Unity Ads documentation.)

    Unity Ads Dashboard showing placement information

Still need help? Get in touch!
Last updated on 23rd Oct 2017