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

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 early in the game’s runtime lifecycle, preferably at launch, using the copied Game ID string, gameId:

         Advertisement.Initialize(string gameId)
    

Showing ads

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");
        // Reward your player here.

    }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 .) Name the script UnityAdsButton to match the class name.
  3. Open the script and add the following code:

    Note: If you are using engine integrated version of Ads SDK, you need to remove the two sections of code that are marked with ONLY NECESSARY FOR ASSET PACKAGE INTEGRATION.
using UnityEngine;
using UnityEngine.UI;
using UnityEngine.Advertisements;

[RequireComponent(typeof(Button))]
public class UnityAdsButton : MonoBehaviour
{
    //---------- ONLY NECESSARY FOR ASSET PACKAGE INTEGRATION: ----------//
    #if UNITY_IOS
    private string gameId = "1486551";
    #elif UNITY_ANDROID
    private string gameId = "1486550";
    #endif
    //-------------------------------------------------------------------//

    Button m_Button;

    public string placementId = "rewardedVideo";

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

        //---------- 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 15th Oct 2018