Unity API reference

Overview

This article documents API for the following namespaces:

• UnityEngine.Advertisements
  • UnityEngine.Advertisements.Banner
• UnityEngine.Monetization

Advertisements

Use this namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.

using UnityEngine.Advertisements;

Initialize

Initializes the ads service, with a specified Game ID, test mode status, and Placement load setting.

public static void Initialize(string gameId, bool testMode, bool enablePerPlacementLoad)

Load

Loads ad content for a specified Placement. If you initialized the SDK with enablePerPlacementLoad enabled, you must call Load before calling Show.

public static void Load (string placementId)

Note: The Load API is in closed beta and available upon invite only. If you would like to be considered for the beta, please contact Unity Ads support.

IsReady

Returns whether an ad is ready to be shown for the specified Placement.

static bool IsReady (string placementId) 

PlacementState

The enumerated states of a Unity Ads Placement.

enum UnityEngine.Advertisements.PlacementState

Retrieve the PlacementState value with the following function:

static PlacementState GetPlacementState (string PlacementId)

Show

Shows content in the specified Placement, if it is ready.

static void Show (string placementId) 

IUnityAdsListener

An interface for handling various states of an ad. Implement this listener in your script to define logic for rewarded ads. The interface has the following methods:

public interface IUnityAdsListener {
    void OnUnityAdsReady (string placementId);
    void OnUnityAdsDidError (string message);
    void OnUnityAdsDidStart (string placementId);
    void OnUnityAdsDidFinish (string placementId, ShowResult showResult);
}

Note: Unity recommends implementing them all of these methods in your code, even if you don’t use them all.

OnUnityAdsReady

An IUnityAdsListener method that handles logic for ad content being ready to display through a specified Placement. For example:

void OnUnityAdsReady (string placementId) {
    Advertisement.Show (placementId);
}

OnUnityAdsDidError

An IUnityAdsListener method that handles logic for ad content failing to display because of an error. For example:

void OnUnityAdsDidError (string errorMessage) {
    Debug.LogWarning (errorMessage);
}

OnUnityAdsDidStart

An IUnityAdsListener method that handles logic for the player triggering an ad to play. For example:

void OnUnityAdsDidStart (string placementId) {
    Debug.Log (“The ad started playing.”);
}

OnUnityAdsDidFinish

An IUnityAdsListener method that handles logic for an ad finishing. Define conditional behavior for different finish states by accessing the ShowResult result from the listener (documented below). For example:

void OnUnityAdsDidFinish (string placementId, ShowResult showResult) {
    If (showResult == ShowResult.Finished) {
        // Reward the user for watching the ad to completion.
    } else if (showResult == ShowResult.Skipped) {
        // Do not reward the user for skipping the ad.
    } else if (showResult == ShowResult.Failed) {
        Debug.LogWarning (“The ad did not finish due to an error.);
    }
}

ShowResult

The enumerated states of the end-user’s interaction with the ad. The SDK passes this value to the OnUnityAdsDidFinish callback method when the ad completes.

enum UnityEngine.Advertisements.ShowResult

AddListener

SDK versions 3.1+ allow you to register multiple listeners. This is especially helpful for mediation customers.

public static void AddListener (IUnityAdsListener listener)

RemoveListener

Allows you to remove an active listener.

public static void RemoveListener (IUnityAdsListener listener) 

Banner

A static class for implementing banner ads.

SetPosition

Sets the position of the banner ad, using the BannerPosition enum.

public void SetPosition (BannerPosition bannerPosition)

BannerPosition

The enumerated positions you can set as an anchor for banner ads.

public enum BannerPosition {
    TOP_LEFT,
    TOP_CENTER,
    TOP_RIGHT,
    BOTTOM_LEFT,
    BOTTOM_CENTER,
    BOTTOM_RIGHT,
    CENTER
}

Load

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

To check if the content successfully loaded and is ready to display, use the following method:

public static bool isLoaded ()    

Show

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

BannerOptions

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

BannerLoadOptions

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

Hide

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

public static void Hide (bool destroy = false);

Service properties

isInitialized

Returns whether the advertisement system is successfully initialized.

static bool isInitialized [get, set] 

isSupported

Returns whether the current platform is supported by the SDK.

static bool isSupported [get] 

debugMode

Controls the amount of logging output from the SDK.

static bool debugMode [get, set]

version

Returns the active Unity Ads SDK version.

static string version [get]

isShowing

Returns whether an ad is currently showing.

static bool isShowing [get, set] 

Back to top

Monetization

Use the Monetization namespace to implement Personalized Placements.

using UnityEngine.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.

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.

gamerSid

A unique server identifier used in server-to-server redeem callbacks.

public string gamerSid

Back to top