Grow your game Unity Ads Unity Ads SDK integration guide for Unity developers Unity Ads SDK API reference Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in C# to integrate and control ad behavior in your Unity project.
Read time 7 minutes
Last updated a day ago Use the 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 Interfaces Classes
Advertisement
Initialize
public static void Initialize(string gameId, bool testMode, IUnityAdsInitializationListener initializationListener)
Initializes the ads service, with a specified Game ID , test mode status, and ad unit load setting.
Parameter Description The platform-specific Unity game identifier for your project, found on
the developer dashboard. Use Test mode to test your integration without serving live ads. Use
to initialize in test mode. Optionally enables the SDK with
IUnityAdsInitializationListener
Load
public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)
Loads ad content for a specified ad unit.
Parameter Description The identifier for the ad unit you want to load with ad content. Optionally loads ad content with
IsReady
static bool IsReady (string adUnitId)
Returns if an ad is ready to show in the specified ad unit. If you initialized the SDK with enabled, you must call
Parameter Description The identifier for the ad unit you want to query.
Show
public static void Show(string adUnitId, ShowOptions showOptions, IUnityAdsShowListener showListener)
Displays loaded ad content in a specified ad unit.
Parameter Description The identifier for the ad unit you want to show. A collection of options, including Optionally shows content with
Note
If you call without specifying an ad unit ID, the method shows loaded content in the Unity Standard Placement. In SDK versions 4.0 and higher, you must specify an ad unit ID. AddListener
public static void AddListener(IUnityAdsListener listener)
Adds a listener that will receive Unity Ads callbacks. In versions 3.1.0 and later, you can register multiple listeners. This is especially helpful for mediation customers.
Parameter Description A listener for Unity Ads callbacks.
RemoveListener
public static void RemoveListener(IUnityAdsListener listener)
Removes an active
Parameter Description A listener for Unity Ads callbacks.
GetPlacementState
public static PlacementState GetPlacementState(string adUnitId)
Returns the state of a specified ad unit.
Parameter Description The identifier for the ad unit you want to query
isInitialized
public static bool isInitialized
Returns if the SDK is initialized, and if it isn't.
isSupported
public static bool isSupported
Returns if the SDK is supported on the current platform, and if it isn't.
debugMode
public static bool debugMode
Returns if the SDK is in debug mode, and if it isn't. Debug mode controls the level of logging from the SDK.
version
public static string version
Returns the current SDK version.
isShowing
public static bool isShowing
Returns if an ad is currently showing, and if it isn't.
Banner
Use this class to implement banner ads .
Load
public static void Load(string adUnitId, BannerLoadOptions options)
Loads ad content for a specified Banner ad unit. If you initialized the SDK with enabled, you must call before calling
Parameter Description The identifier for the Banner ad unit you want to load. A collection of options that notify the SDK of
events when loading the banner.
Show
public static void Show(string adUnitId, BannerOptions options)
Shows ad content for a specified Banner ad unit. You must call
Parameter Description The identifier for the Banner ad unit you want to load. A collection of options that notify the SDK of events when displaying the banner.
Hide
public static void Hide(bool destroy = false)
Allows you to hide a banner ad without destroying it altogether.
SetPosition
public void SetPosition (BannerPosition bannerPosition)
Sets the position of the banner ad on the device.
Parameter Description The position to use as an anchor for your banner ad.
isLoaded
public static bool isLoaded
Returns if a banner ad is currently loaded to show, and if it isn't.
ShowOptions
Implement these options to notify the SDK of events when showing content in an ad unit. Use ShowOptions.resultCallback
resultCallback
public ShowResult resultCallback { get; set; }
This callback receives the result of an ad.
Important
Obsolete : Implement Advertisement.AddListenergamerSid
public string gamerSid { get; set; }
Specify an identifier for a specific user in the game.
BannerLoadOptions
Implement these options to notify the SDK of events when loading a banner ad.
loadCallback
public LoadCallback loadCallback { get; set; }
This callback fires when the Banner ad unit successfully loads content that is ready to show.
errorCallback
public ErrorCallback errorCallback { get; set; }
This callback fires when the Banner ad unit failed to load content.
BannerOptions
Implement these options to notify the SDK of events when displaying a banner ad.
bannerCallback
public BannerCallback bannerCallback { get; set; }
This callback fires when the banner is visible to the user.
hideCallback
public BannerCallback hideCallback { get; set; }
This callback fires when the banner is hidden from the user.
clickCallback
public BannerCallback clickCallback { get; set; }
This callback fires when the user clicks the banner.
Enums
PlacementState
The enumerated states of an ad unit.
Value Description The ad unit is ready to show ads. The ad unit is not available. The ad unit has been disabled. The ad unit is waiting to be ready. The ad unit has no ads to show.
ShowResult
The enumerated states of the user's interaction with the ad. The SDK passes this value to the
Value Description Indicates that the ad failed to complete due to a Unity service error. Indicates that the user skipped the ad. Indicates that the user successfully finished watching the ad.
UnityAdsInitializationError
The enumerated reasons for SDK initialization to fail.
Value Description An error occurred for unknown reasons. An error occurred due to the environment or internal services. An error occurred due to invalid arguments in the An error occurred due to a URL being blocked.
UnityAdsLoadError
The enumerated reasons for an ad unit failing to load.
Value Description The ad failed to load due to the SDK not being initialized. The ad failed to load due to an internal Unity Ads service error. The ad failed to load due to invalid arguments in the The ad failed to load because no content was available from the network. The ad failed to load within the specified timeframe. The ad failed to load for an unknown reason.
UnityAdsShowCompletionState
The enumerated causes for the ad to have finished.
Value Description Indicates that the user skipped the ad. Indicates that the ad played in its entirety. This typically indicates that the user can be rewarded for watching the full ad. The cause of the ad finishing is unknown.
UnityAdsShowError
The enumerated reasons for an ad failing to show.
Value Description The ad failed to show due to the SDK not being initialized. The ad failed to show because the ad unit was not ready. The ad failed to show because of a media player error. The ad failed to show due to invalid arguments in the The ad failed to show because of an internet connection error. The ad failed to show because an ad was already showing. The ad failed to show due to an internal Unity Ads service error. The ad failed to show for an unknown reason.
BannerPosition
The enumerated positions to anchor a banner on the device display.
Value Description Anchor the banner to the top-left of the screen. Anchor the banner to the top-center of the screen. Anchor the banner to the top-right of the screen. Anchor the banner to the bottom-left of the screen. Anchor the banner to the bottom-center of the screen. Anchor the banner to the bottom-right of the screen. Anchor the banner to the center of the screen.
Interfaces
IUnityAdsInitializationListener
public interface IUnityAdsInitializationListener { void OnInitializationComplete(); void OnInitializationFailed(UnityAdsInitializationError error, string message); }
Implement this interface to handle
OnInitializationComplete
This callback method handles logic for the SDK successfully initializing.
OnInitializationFailed
This callback method handles logic for the SDK failing to initialize.
IUnityAdsLoadListener
public interface IUnityAdsLoadListener { void OnUnityAdsAdLoaded(string adUnitId); void OnUnityAdsFailedToLoad(string adUnitId, UnityAdsLoadError error, string message); }
Implement this interface to handle
OnUnityAdsLoaded
This callback method handles logic for the ad unit successfully loading.
Parameter Description The identifier for the ad unit that loaded content.
OnUnityAdsFailedToLoad
This callback method handles logic for the ad unit failing to load.
Parameter Description The identifier for the ad unit that failed to load. The A message associated with the error.
IUnityAdsShowListener
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
OnUnityAdsShowFailure
This callback method handles logic for the ad unit failing to show.
Parameter Description The identifier for the ad unit that failed to show. The A message associated with the error.
OnUnityAdsShowStart
This callback method handles logic for the ad starting to play.
Parameter Description The identifier for the ad unit showing the content.
OnUnityAdsShowClick
This callback method handles logic for the user clicking on the ad.
Parameter Description The identifier for the ad unit showing the content.
OnUnityAdsShowComplete
This callback method handles logic for the ad finishing.
Parameter Description The identifier for the ad unit showing the content. Indicates the final state of the ad (whether the ad was skipped or completed).
IUnityAdsListener
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 .
OnUnityAdsReady
Specify logic for ad content being ready to display through a specified ad unit.
Parameter Description The identifier for the ad unit that is ready.
OnUnityAdsDidError
Specify logic for ad content failing to display due to an error.
Parameter Description A message associated with the error.
OnUnityAdsDidStart
Specify logic for the player triggering an ad to show.
Parameter Description The identifier for the ad unit
that is showing content.
OnUnityAdsDidFinish
Specify logic for the player watching the ad in its entirety.
Parameter Description The identifier for the ad unit that finished showing. The resulting user event of the ad showing.