Knowledge base

(Legacy) Ads integration

Note: This legacy guide covers Unity Ads integration in C# using the Advertisement API, which is still fully supported. However, Unity recommends using the Monetization API available in SDK versions 3.0+, to take advantage of advanced optimization features. For more information, click here.

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

Download the latest SDK from the Asset store. For information on downloading and installing Asset packages, see Asset packages documentation.

Creating a Placement

Placements are triggered events within your game that display monetization content. Manage Placements from the Operate tab of the Developer Dashboard by selecting your Project, then selecting Monetization > Placements from the left navigation bar.

Click the ADD PLACEMENT button to bring up the Placement creation prompt. Name your Placement and select its type:

  • Select Non-rewarded to show basic interstitial ads or promotional content. Non-rewarded Placements allow players to skip the ad after a specified period of time.
  • Select Rewarded to allow players to opt-in to viewing ads in exchange for incentives. Rewarded Placements do not allow the player to skip the ad.
  • Select Banner to create a dedicated Banner ad Placement.

Every Unity Ads-enabled project has a (non-rewarded) ‘video’ and (rewarded) ‘rewardedVideo’ Placement by default. Feel free to use one of these for your first implementation if they suit your needs, or create your own.

Initializing the SDK

To initialize the SDK, you must reference your Project’s Game ID for the appropriate platform. You can locate the ID on the Operate tab of the Developer Dashboard by selecting the Project, then selecting Monetization > Platforms from the left navigation bar.

Locating your Game ID in the Developer Dashboard

In your game script header, include the UnityEngine.Advertisement namespace. Initialize the SDK early in the game’s run-time life cycle, preferably at launch, using the Initialize function. For example:

using UnityEngine.Advertisement;

public class UnityAdsScript : MonoBehaviour { 

    string gameId = "1234567";
    bool testMode = true;

    void Start () {
        Advertisement.Initialize (gameId, testMode);
    }
}

Showing ads

With the Service enabled and Placement created, simply call the Show method 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.
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 the Developer Dashboard to modify placements and other game-specific settings in your project.

  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 documentation on Placements.)

    Unity Ads Dashboard showing placement information

Still need help? Get in touch!
Last updated on 16th Nov 2018