-
Notifications
You must be signed in to change notification settings - Fork 44
api unity
/*
Title: Unity API reference
Description:
Sort: 5
*/
Use the Advertisements
namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.
using UnityEngine.Advertisements;
This article contains the following API documentation:
Classes
Enums
- PlacementState
- ShowResult
- UnityAdsInitializationError
- UnityAdsLoadError
- UnityAdsShowError
- UnityAdsShowCompletionState
- UnityAdsShowError
- BannerPosition
Interfaces
public static void Initialize(string gameId, bool testMode, bool enablePerPlacementLoad, IUnityAdsInitializationListener initializationListener)
Initializes the ads service, with a specified Game ID, test mode status, and Ad Unit load setting.
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 |
Optionally enables the SDK with the Load API lifecycle (versions 3.5.0 and higher). |
initializationListener |
Optionally enables the SDK with IUnityAdsInitializationListener callbacks (versions 3.7.0 and higher). |
public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)
Loads ad content for a specified Ad Unit. If you initialized the SDK with enablePerPlacementLoad
enabled, you must call Load
before calling Show
.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit you want to load with ad content. |
loadListener |
Optionally loads ad content with IUnityAdsLoadListener callbacks (versions 3.7.0 and higher). |
static bool IsReady (string adUnitId)
Returns true
if an ad is ready to show in the specified Ad Unit. If you initialized the SDK with enablePerPlacementLoad
enabled, you must call Load
before calling Show
.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit you want to query. |
Note: If you call IsReady()
without specifying an Ad Unit ID, the method returns results for the Unity Standard Placement.
public static void Show(string adUnitId, ShowOptions showOptions, IUnityAdsShowListener showListener)
Displays loaded ad content in a specified Ad Unit.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit you want to show. |
showOptions |
A collection of options, including resultCallback , for modifying ad behavior. |
showListener |
Optionally shows content with IUnityAdsShowListener callbacks (versions 3.7.0 and higher). |
Note: If you call Show()
without specifying an Ad Unit ID, the method shows loaded content in the Unity Standard Placement.
public static void AddListener(IUnityAdsListener listener)
Adds a listener that will recieve Unity Ads callbacks. Versions 3.1.0 and higher allow you to register multiple listeners. This is especially helpful for mediation customers.
Parameter | Description |
---|---|
listener |
A listener for Unity Ads callbacks. |
public static void RemoveListener(IUnityAdsListener listener)
Removes an active IUnityAdsListener
.
Parameter | Description |
---|---|
listener |
A listener for Unity Ads callbacks. |
public static PlacementState GetPlacementState(string adUnitId)
Returns the state of a specified Ad Unit.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit you want to query. |
public static bool isInitialized
Returns true
if the SDK is initialized successfully, and false
if it isn't.
public static bool isSupported
Returns true
if the SDK is supported on the current platform, and false
if it isn't.
public static bool debugMode
Returns true
if the SDK is is in debug mode, and false
if it isn't. Dubug mode controls the level of logging from the SDK.
public static string version
Returns the current SDK version.
public static bool isShowing
Returns true
if an ad is currently showing, and false
if it isn't.
Use this class to implement banner ads.
public static void Load(string adUnitId, BannerLoadOptions options)
Loads ad content for a specified Banner Ad Unit. If you initialized the SDK with enablePerPlacementLoad
enabled, you must call Load
before calling Show
.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Banner Ad Unit you want to load with ad content. |
options |
A collection of options that notify the SDK of events when loading the banner. |
public static void Show(string adUnitId, BannerOptions options)
Shows ad content for a specified Banner Ad Unit. If you initialized the SDK with enablePerPlacementLoad
enabled, you must call Load
before calling Show
.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Banner Ad Unit you want to load with ad content. |
options |
A collection of options that notify the SDK of events when displaying the banner. |
public static void Hide(bool destroy = false)
Allows you to hide a banner ad without destroying it altogether.
public void SetPosition (BannerPosition bannerPosition)
Sets the position of the banner ad on the device.
Parameter | Description |
---|---|
bannerPosition |
The position to use as an anchor for your banner ad. |
public static bool isLoaded
Returns true
if a banner ad is currently loaded to show, and false
if it isn't.
Implement these options to notify the SDK of events when showing content in an Ad Unit. Use ShowOptions.resultCallback to pass a ShowResult enum back to Show when the ad finishes.
public Action<ShowResult> resultCallback { get; set; }
This callback receives the result of an ad.
Obsolete: Implement IUnityAdsListener
and call Advertisement.AddListener()
.
public string gamerSid { get; set; }
Specify an identifier for a specific user in the game.
Implement these options to notify the SDK of events when loading a banner ad.
public LoadCallback loadCallback { get; set; }
This callback fires when the Banner Ad Unit successfully loads content that is ready to show.
public ErrorCallback errorCallback { get; set; }
This callback fires when the Banner Ad Unit failed to load content.
Implement these options to notify the SDK of events when displaying a banner ad.
public BannerCallback bannerCallback { get; set; }
This callback fires when the Banner is visible to the user.
public BannerCallback hideCallback { get; set; }
This callback fires when the banner is hidden from the user.
public BannerCallback clickCallback { get; set; }
This callback fires when the user clicks the banner.
The enumerated states of an Ad Unit.
Value | Description |
---|---|
Ready |
The Ad Unit is ready to show ads. |
NotAvailable |
The Ad Unit is not available. |
Disabled |
The Ad Unit has been disabled. |
Waiting |
The Ad Unit is waiting to be ready. |
NoFill |
The Ad Unit has no advertisements to show. |
The enumerated states of the user’s interaction with the ad. The SDK passes this value to the OnUnityAdsDidFinish
callback method when the ad completes.
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. |
The enumerated reasons for SDK initialization to fail.
Value | Description |
---|---|
UNKNOWN |
An error occurred for unknown reasons. |
INTERNAL_ERROR |
An error occurred due to the environment or internal services. |
INVALID_ARGUMENT |
An error occurred due to invalid arguments in the Initialize method. |
AD_BLOCKER_DETECTED |
An error occurred due to a URL being blocked. |
The enumerated reasons for an Ad Unit failing to load.
Value | Description |
---|---|
INITIALIZE_FAILED |
The ad failed to load due to the SDK not being initialized. |
INTERNAL_ERROR |
The ad failed to load due to an internal Unity Ads service error. |
INVALID_ARGUMENT |
The ad failed to load due to invalid arguments in the Load method. |
NO_FILL |
The ad failed to load because no content was available from the network. |
TIMEOUT |
The ad failed to load within the specified timeframe. |
UNKNOWN |
The ad failed to load for an unknown reason. |
The enumerated causes for the ad to have finished.
Value | Description |
---|---|
SKIPPED |
Indicates that the user skipped the ad. |
COMPLETED |
Indicates that the ad played in its entirety. This typically indicates that the user can be rewarded for watching the full ad. |
UNKNOWN |
The cause of the ad finishing is unknown. |
The enumerated reasons for an Ad Unit failing to show.
Value | Description |
---|---|
NOT_INITIALIZED |
The ad failed to show due to the SDK not being initialized. |
NOT_READY |
The ad failed to show because the Ad Unit was not ready. |
VIDEO_PLAYER_ERROR |
The ad failed to show because of a media player error. |
INVALID_ARGUMENT |
The ad failed to show due to invalid arguments in the Show method. |
NO_CONNECTION |
The ad failed to show because of an internet connection error. |
ALREADY_SHOWING |
The ad failed to show because an ad was already showing. |
INTERNAL_ERROR |
The ad failed to show due to an internal Unity Ads service error. |
UNKNOWN |
The ad failed to show for an unknown reason. |
The enumerated positions to anchor a banner on the device display.
Value | Description |
---|---|
TOP_LEFT |
Anchor the banner to the top-left of the screen. |
TOP_CENTER |
Anchor the banner to the top-center of the screen. |
TOP_RIGHT |
Anchor the banner to the top-right of the screen. |
BOTTOM_LEFT |
Anchor the banner to the bottom-left of the screen. |
BOTTOM_CENTER |
Anchor the banner to the bottom-center of the screen. |
BOTTOM_RIGHT |
Anchor the banner to the bottom-right of the screen. |
CENTER |
Anchor the banner to the center of the screen. |
public interface IUnityAdsInitializationListener {
void OnInitializationComplete();
void OnInitializationFailed(UnityAdsInitializationError error, string message);
}
Implement this interface to handle Initialize
results.
This callback method handles logic for the SDK successfully initializing.
This callback method handles logic for the SDK failing to initialize.
Parameter | Description |
---|---|
error |
The UnityAdsInitializationError that caused initialization to fail. |
message |
A message associated with the error. |
public interface IUnityAdsLoadListener {
void OnUnityAdsAdLoaded(string adUnitId);
void OnUnityAdsFailedToLoad(string adUnitId, UnityAdsLoadError error, string message);
}
Implement this interface to handle Advertisement.Load
results.
This callback method handles logic for the Ad Unit successfully loading.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit that loaded content. |
This callback method handles logic for the Ad Unit failing to load.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit that failed to load content. |
error |
The UnityAdsLoadError that caused the load to fail. |
message |
A message associated with the error. |
public interface IUnityAdsShowListener {
void OnUnityAdsShowFailure(string adUnitId, UnityAdsShowError error, string message);
void OnUnityAdsShowStart(string adUnitId);
void OnUnityAdsShowClick(string adUnitId);
void OnUnityAdsShowComplete(string adUnitId, UnityAdsShowCompletionState showCompletionState);
}
Implement this interface to handle Advertisement.Show
results.
This callback method handles logic for the Ad Unit failing to show.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit that failed to show content. |
error |
The UnityAdsShowError that caused the show to fail. |
message |
A message associated with the error. |
This callback method handles logic for the ad starting to play.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit showing the content. |
This callback method handles logic for the user clicking on the ad.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit showing the content. |
This callback method handles logic for the ad finishing.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit showing the content. |
showCompletionState |
Indicates whether the ad was skipped or completed. |
public interface IUnityAdsListener
{
void OnUnityAdsReady(string adUnitId);
void OnUnityAdsDidError(string message);
void OnUnityAdsDidStart(string adUnitId);
void OnUnityAdsDidFinish(string adUnitId, ShowResult showResult);
}
Implement this interface to handle various states of an ad. Implement this listener in your script to define logic for rewarded ads.
Specify logic for ad content being ready to display through a specified Ad Unit.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit that is ready. |
Specify logic for ad content failing to display due to an error.
Parameter | Description |
---|---|
message |
A message associated with the error. |
Specify logic for the player triggering an ad to show.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit that is showing the ad. |
Specify logic for the player watching the ad in its entirety.
Parameter | Description |
---|---|
adUnitId |
The identifier for the Ad Unit that finished showing. |
showResult |
The resulting user event of the ad showing. |