Unity API reference
Overview
This article documents API for the following namespaces:
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)
Parameter | Description |
---|---|
gameId |
The platform-specific Unity game identifier for your Project, found on the developer dashboard. |
testMode |
Test mode allows you to test your integration without serving live ads. Use true to initialize in test mode. |
enablePerPlacementLoad |
Enables the Load API lifecycle. |
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
Value | Description |
---|---|
Ready |
The Placement is ready to show ads. |
NotAvailable |
The Placement is not available. |
Disabled |
The Placement has been disabled. |
Waiting |
The Placement is waiting to be ready. |
NoFill |
The Placement has no advertisements to show. |
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
Value | Description |
---|---|
Failed |
Indicates that the ad failed to complete due to a Unity service error. |
Skipped |
Indicates that the user skipped the ad. |
Finished |
Indicates that the user successfully finished watching the ad. |
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.
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 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. |
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.
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 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 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. |
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. |
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]
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.
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.
gamerSid
A unique server identifier used in server-to-server redeem callbacks.
public string gamerSid