Skip to content

integration guide unity

Jump to bottom
Jesse Reiter-Skolnick edited this page Oct 17, 2018 · 35 revisions

/*
Title: Integration guide for Unity Description: A guide to integrating Unity Ads in Unity (C#)
Sort: 1 */

Overview

This guide covers integration for implementing Unity Ads in your made-with-Unity game.

  • If you are an iOS developer using Objective-C, click here.
  • If you are an Android developer using Java, click here.

Unity’s monetization platform provides you with powerful revenue tools. If your game uses in-app purchases as well as ads, Unity’s machine learning data model can seamlessly blend content types for an optimized monetization strategy. To learn more about how Unity helps you optimize revenue, see documentation on Personalized Placements.

In this guide:

Basic implementation

Configuring your Project

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.

Setting build targets in the Unity Editor

Installing Unity Ads

To ensure the latest version of Unity Ads, download it from the Asset store. The Monetization API requires SDK 3.0 or later. 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.Monetization namespace. Initialize the SDK early in the game’s run-time life cycle, preferably at launch, using the Initialize function. For example:

using UnityEngine.Monetization;

public class UnityAdsScript : MonoBehaviour { 

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

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

Implementing basic (non-rewarded) ads

PlacementContent is an object representing monetization content that your Placement can display (for more information, see documentation on Content types and Personalized Placements). Use the GetPlacementContent function to retrieve content when it’s ready to display, and the Show function to display it. For example:

using UnityEngine.Monetization;

public class UnityAdsPlacement : MonoBehaviour {

    public string placementId = "video";

    public void ShowAd () {
        StartCoroutine (ShowAdWhenReady ());
    }

    private IEnumerator ShowAdWhenReady () {
        while (!Monetization.IsReady (placementId)) {
            yield return new WaitForSeconds(0.25f);
        }

        ShowAdPlacementContent ad = null;
        ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;

        if(ad != null) {
            ad.Show ();
        }
    }
}

In this example, the coroutine checks the passed Placement ID for available PlacementContent using the IsReady function. If content is available, it’s stored as a variable and executed with the Show function.

Implementing rewarded 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. For more information on how to effectively design your rewarded ads, see documentation on Ads best practices.

To reward players for watching ads, follow the same steps as detailed in the basic implementation section, but show the ad using a reward callback method with custom logic for players completing the ad.

Selecting a Placement

You must display rewarded ads through Rewarded Placements. Every Unity Ads-enabled Project also has a ‘rewardedVideo’ Placement by default. Feel free to use this for your implementation, or create your own (but make sure your Placement is configured as Rewarded).

Adding a callback method to your script

The Show function accepts a callback that the SDK uses to return a ShowResult enum. This result indicates whether the player finished or skipped the ad. Use this information to write a custom function for how to handle each scenario. For example:

using UnityEngine.Monetization;

public class RewardedAdsPlacement : MonoBehaviour {

    public string placementId = "rewardedVideo";

    public void ShowAd () {
        StartCoroutine (WaitForAd ());
    }

    IEnumerator WaitForAd () {
        while (!Monetization.IsReady (placementId)) {
            yield return null;
        }

        ShowAdPlacementContent ad = null;
        ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;

        if (ad != null) {
            ad.Show (AdFinished);
        }
    }

    void AdFinished (ShowResult result) {
        if (result == ShowResult.Finished) {
            // Reward the player
        }
    }
}

Rewarded ads button code example

Rewarded ads usually use a button that prompts players to opt in to watching the ad. The following describes how to create a rewarded ads button that displays an ad when pressed, as long as content is available.

  1. In the Unity Editor, select Game Object > UI > Button to add a Button to your Scene.
  2. With the Button selected, in the Inspector, click Add Component > New Script to add a script component to it. Name the script UnityAdsButton to match the class name.
  3. Open the script and add the following example code:
using UnityEngine;
using UnityEngine.UI;
using UnityEngine.Monetization;

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

    public string placementId = "rewardedVideo";
    private Button adButton;

#if UNITY_IOS
   private string gameId = "1234567";
#elif UNITY_ANDROID
    private string gameId = "7654321";
#endif

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

        if (Monetization.isSupported) {
            Monetization.Initialize (gameId, true);
        }
  
    void Update () {
        if (adButton) {
            adButton.interactable = Monetization.IsReady (placementId);
        }
    }

    void ShowAd () {
        ShowAdCallbacks options = new ShowAdCallbacks ();
        options.finishCallback = HandleShowResult;
        ShowAdPlacementContent ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;
        ad.Show (options);
    }

    void HandleShowResult (ShowResult result) {
        if (result == ShowResult.Finished) {
            // Reward the player
        } else if (result == ShowResult.Skipped) {
            Debug.LogWarning ("The player skipped the video - DO NOT REWARD!");
        } else if (result == ShowResult.Failed) {
            Debug.LogError ("Video failed to show");
        }
    }
}

Note: This example checks at a specific point in the game whether PlacementContent is ready to display. As an alternate method, you can implement a listener to notify you when content is available.

Implementing Banner ads

Placement configuration

Banner ads require a specific type of dedicated banner Placement. Banners currently display anchored on the bottom-center of the screen.

Example of a banner ad in-game

Script implementation

In your Placement script header, declare the UnityEngine.Advertisement namespace, which contains the Banner class. Next, initialize the SDK and use Advertisement.Banner.Show () to display a banner ad. For example:

using UnityEngine.Advertisement;

public class UnityBannerAds : MonoBehaviour {

    Start () {
        Advertisement.Initialize ("1234567", true);
        ShowBannerAd ();
    }

    public void ShowBannerAd () {
        Advertisement.Banner.Show ();
    }
}

Testing

Prior to publishing your game, enable test mode by following these steps:

  1. From the Operate tab of the Developer Dashboard, select your Project.
  2. Select Monetization > Platforms from the left navigation bar.
  3. Select the desired platform, then select the SETTINGS tab.
  4. Scroll down to the TEST MODE section and toggle override client test mode, then select the Force test mode ON radio button.

In the Unity Editor, click the play button to run your Project and test your ads implementation.

Note: You must enable test mode before testing ads integration, to avoid getting flagged for fraud.

Optimizing your revenue

Congratulations on implementing Unity Ads! Our goal is to make it easy for you to maximize your revenue. With that in mind, consider these next steps:

  • Does your game use in-app purchasing (IAP)?
    • If yes, implement IAP Promo to promote your in-app offers.
    • If no, create an in-app store with Unity IAP.
  • When you have Ads and IAP Promo set up, use Personalized Placements to turbocharge your ads and IAP strategy and provide revenue lift for your entire game.
  • Review our Best practices guide for insight on how to design effective ad mechanics.

Back to top

Unity API reference

Monetization

Initialize

Initializes the SDK for your Project.

public static void Initialize (string gameID, bool testMode)

The gameId parameter is the Project’s Game ID, which you can find on the Developer Dashboard. The testMode parameter indicates whether the game is in test mode. When testMode is true, you will only see test ads. When testMode is false, you will see live ads. It is important to use test mode prior to launching your game, to avoid being flagged for fraud.

IsReady

Checks if PlacementContent is ready for the given Placement.

public static boolean IsReady (string placementId);

The placementId parameter is the Placement ID as configured in the Developer Dashboard. The function returns true if the PlacementContent is ready, or false if it isn’t.

GetPlacementContent

Returns the PlacementContent object for the given Placement.

public static PlacementContent GetPlacementContent (string placementId);

The placementId parameter is the Placement ID as configured in the Developer Dashboard. The function returns a PlacementContent object if one is available, or null if it isn’t.

Note: When setting the PlacementContent as a variable, you must cast it as the correct type (ShowAdPlacementContent or PromoAdPlacementContent). For more information, see documentation on content types.

IMonetizationListener

An interface that you implements and pass to the SDK.

public interface IMonetizationListener {   
    void OnPlacementContentReady (string placementId, PlacementContent placementContent);   
    void OnPlacementContentStateChange (string placementId, PlacementContent placementContent, Monetization.PlacementContentState previousState, Monetization.PlacementContentState newState);
}

OnPlacementContentReady

Takes a Placement ID and PlacementContent object, and dictates how the SDK handles content that is ready to show.

OnPlacementContentStateChange

Dictates how the SDK handles a state change in the passed PlacementContent.

SetListener

Sets the listener for PlacementContent events. The listener parameter is the listener for event callbacks.

public static void SetListener (IMonetizationListener listener);

GetListener

Returns the current Monetization listener. The listener object is the listener for event callbacks.

public static IMonetizationListener GetListener ();

PlacementContent

An object representing monetization content that your Placement can display.

RewardablePlacementContent

Extends the PlacementContent class, providing extensions for rewardable content.

ShowAdPlacementContent

Extends the RewardablePlacementContent class, providing functionality for video ad content.

Show

When PlacementContent is cast as ShowAdPlacementContent, display it using the Show function. You may pass a callback method indicating whether the ad was finished, skipped, or failed to display, in order to handle in-game rewards.

public void Show (ShowAdCallbacks showAdCallbacks)

public void Show (ShowAdFinishCallback finishCallback)

For rewarded PlacementContent, use listeners to check if the content completes and handle the desired behavior.

ShowAdCallbacks

A ShowResult enum is passed to [[ShowOptions.resultCallback]] after the ad runs.

Value Description
Finished Indicates that the player watched the ad to completion.
Skipped Indicates that the player did not allow the ad to complete.
Failed Indicates that the ad failed to display. 
public delegate void ShowAdFinishCallback (ShowResult finishState);

public delegate void ShowAdStartCallback ();

public struct ShowAdCallbacks {
    public ShowAdFinishCallback finishCallback;
    public ShowAdStartCallback startCallback;
}

PromoAdPlacementContent

Extends the ShowAdPlacementContent class, providing functionality for IAP Promo content. For more information, see documentation on Native Promo.

Banner

Load

The basic method for loading banner ad content. You can adjust this function with several parameters, depending on your needs.

Method Description
public static void Load () Loads the banner ad with the default Placement ID and no callbacks.
public static void Load (BannerLoadOptions options) Loads the banner ad with the default Placement ID, but fires the loadCallback callback on successful load, and the [errorCallback]((#bannerloadoptions) callback on failure to load.
public static void Load (string placementID) Loads the banner ad with a specific Placement ID, with no callbacks.
public static void Load (string placementID, BannerLoadOptions options) Loads the banner ad with a specific Placement ID, but fires the loadCallback callback on successful load, and the errorCallback callback on failure to load.
public static bool isLoaded () Checks to see if the content successfully loaded and is ready to display.
BannerLoadOptions

Pass these options back to the SDK to notify it of events when loading the banner.

Callback Description
public LoadCallback loadCallback { get; set; } Fires when the banner ad is loaded and available to show.
public ErrorCallback errorCallback { get; set; } This callback fires when an error occurs during the banner ad loading process. If this callback is invoked, assume the banner did not load. You may attempt to call Load again at a later time.

Show

The basic method for displaying Banner ad content. You can adjust this function with several parameters, depending on your needs.

Method Description
public static void Show () Shows the banner ad with the default Placement ID and no callbacks.
public static void Show (BannerOptions options) Shows the banner ad with the default Placement ID, but fires the showCallback callback when the content is visible, and the [hideCallback]((#banneroptions) callback when the content is hidden.
public static void Show (string placementID) Shows the banner ad with a specific Placement ID, with no callbacks.
public static void Show (string placementID, BannerLoadOptions options) Shows the banner ad with a specific Placement ID, but fires the showCallback callback when the content is visible, and the [hideCallback]((#banneroptions) callback when the content is hidden.
BannerOptions

Pass these options back to the SDK to notify it of events within the banner.

Callback Description
public BannerCallback showCallback { get; set; } This callback fires when the banner ad is visible to the player.
public BannerCallback hideCallback { get; set; } This callback fires when the banner ad is hidden from the player.

Hide

This function allows you to hide a banner ad, instead of destroying it altogether.

public static void Hide (bool destroy = false);

Back to top

Clone this wiki locally