-
Notifications
You must be signed in to change notification settings - Fork 43
api unity
/*
Title: Unity API reference
Description:
Sort: 5
*/
This article documents API for the following namespaces:
Use this namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.
using UnityEngine.Advertisements;
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. |
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.
Returns whether an ad is ready to be shown for the specified Placement.
static bool IsReady (string placementId)
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)
Shows content in the specified Placement, if it is ready.
static void Show (string placementId)
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.
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);
}
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);
}
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.”);
}
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.);
}
}
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. |
SDK versions 3.1+ allow you to register multiple listeners. This is especially helpful for mediation customers.
public static void AddListener (IUnityAdsListener listener)
Allows you to remove an active listener.
public static void RemoveListener (IUnityAdsListener listener)
A static class for implementing banner ads.
Sets the position of the banner ad, using the BannerPosition enum.
public void SetPosition (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
}
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 ()
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. |
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. |
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. |
This function allows you to hide a banner ad, instead of destroying it altogether.
public static void Hide (bool destroy = false);
Returns whether the advertisement system is successfully initialized.
static bool isInitialized [get, set]
Returns whether the current platform is supported by the SDK.
static bool isSupported [get]
Controls the amount of logging output from the SDK.
static bool debugMode [get, set]
Returns the active Unity Ads SDK version.
static string version [get]
Returns whether an ad is currently showing.
static bool isShowing [get, set]
Use the Monetization namespace to implement Personalized Placements.
using UnityEngine.Monetization;
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.
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.
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.
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);
}
Takes a Placement ID and PlacementContent object, and dictates how the SDK handles content that is ready to show.
Dictates how the SDK handles a state change in the passed PlacementContent.
Sets the listener for PlacementContent events. The listener parameter is the listener for event callbacks.
public static void SetListener (IMonetizationListener listener);
Returns the current Monetization listener. The listener object is the listener for event callbacks.
public static IMonetizationListener GetListener ();
An object representing monetization content that your Placement can display.
Extends the PlacementContent class, providing extensions for rewardable content.
Extends the RewardablePlacementContent class, providing functionality for video ad content.
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.
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;
}
Extends the ShowAdPlacementContent class, providing functionality for IAP Promo content. For more information, see documentation on Native Promo.
A unique server identifier used in server-to-server redeem callbacks.
public string gamerSid