Unity Ads SDK API reference

Read time 29 minutes

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

Interfaces

Classes
Classes

Initialize
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.

ParameterDescription
gameId

The platform-specific Unity game identifier for your project, found on the developer dashboard.

testMode

Use Test mode to test your integration without serving live ads. Use true to initialize in test mode.

initializationListener

Optionally enables the SDK with IUnityAdsInitializationListener callbacks (versions 3.7.0 and later).

Load
Load

public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)

Loads ad content for a specified ad unit.

ParameterDescription
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 later).

IsReady
IsReady

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.

ParameterDescription
adUnitId
The identifier for the ad unit you want to query.

Show
Show

public static void Show(string adUnitId, ShowOptions showOptions, IUnityAdsShowListener showListener)

Displays loaded ad content in a specified ad unit.

ParameterDescription
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 later).

AddListener
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.

ParameterDescription
listener

A listener for Unity Ads callbacks.

RemoveListener
RemoveListener

public static void RemoveListener(IUnityAdsListener listener)

Removes an active IUnityAdsListener.

ParameterDescription
listener
A listener for Unity Ads callbacks.

GetPlacementState
GetPlacementState

public static PlacementState GetPlacementState(string adUnitId)

Returns the state of a specified ad unit.

ParameterDescription
adUnitId
The identifier for the ad unit you want to query

isInitialized
isInitialized

public static bool isInitialized

Returns true if the SDK is initialized, and false if it isn't.

isSupported
isSupported

public static bool isSupported

Returns true if the SDK is supported on the current platform, and false if it isn't.

debugMode
debugMode

public static bool debugMode

Returns true if the SDK is in debug mode, and false if it isn't. Debug mode controls the level of logging from the SDK.

version
version

public static string version

Returns the current SDK version.

isShowing
isShowing

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.

ParameterDescription
adUnitId

The identifier for the Banner ad unit you want to load.

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. You must call Load before calling Show.

ParameterDescription
adUnitId

The identifier for the Banner ad unit you want to load.

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.

SetPosition
SetPosition

public void SetPosition (BannerPosition bannerPosition)

Sets the position of the banner ad on the device.

ParameterDescription
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.

ShowOptions
ShowOptions

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.

resultCallback
resultCallback

public ShowResult resultCallback { get; set; }

This callback receives the result of an ad.

gamerSid
gamerSid

public string gamerSid { get; set; }

Specify an identifier for a specific user in the game.

BannerLoadOptions
BannerLoadOptions

Implement these options to notify the SDK of events when loading a banner ad.

loadCallback
loadCallback

public LoadCallback loadCallback { get; set; }

This callback fires when the Banner ad unit successfully loads content that is ready to show.

errorCallback
errorCallback

public ErrorCallback errorCallback { get; set; }

This callback fires when the Banner ad unit failed to load content.

BannerOptions
BannerOptions

Implement these options to notify the SDK of events when displaying a banner ad.

bannerCallback
bannerCallback

public BannerCallback bannerCallback { get; set; }

This callback fires when the banner is visible to the user.

hideCallback
hideCallback

public BannerCallback hideCallback { get; set; }

This callback fires when the banner is hidden from the user.

clickCallback
clickCallback

public BannerCallback clickCallback { get; set; }

This callback fires when the user clicks the banner.

Enums
Enums

PlacementState
PlacementState

The enumerated states of an ad unit.

ValueDescription
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 ads to show.

ShowResult
ShowResult

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.

ValueDescription
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.

UnityAdsInitializationError
UnityAdsInitializationError

The enumerated reasons for SDK initialization to fail.

ValueDescription
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.

UnityAdsLoadError
UnityAdsLoadError

The enumerated reasons for an ad unit failing to load.

ValueDescription
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.

UnityAdsShowCompletionState
UnityAdsShowCompletionState

The enumerated causes for the ad to have finished.

ValueDescription
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.

UnityAdsShowError
UnityAdsShowError

The enumerated reasons for an ad failing to show.

ValueDescription
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.

BannerPosition
BannerPosition

The enumerated positions to anchor a banner on the device display.

ValueDescription
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.

Interfaces
Interfaces

IUnityAdsInitializationListener
IUnityAdsInitializationListener

public interface IUnityAdsInitializationListener {
  void OnInitializationComplete();
  void OnInitializationFailed(UnityAdsInitializationError error, string message);
}

Implement this interface to handle Initialize results.

OnInitializationComplete
OnInitializationComplete

This callback method handles logic for the SDK successfully initializing.

OnInitializationFailed
OnInitializationFailed

This callback method handles logic for the SDK failing to initialize.

ParameterDescription
error

The UnityAdsInitializationError that caused initialization to fail.

message
A message associated with the error.

IUnityAdsLoadListener
IUnityAdsLoadListener

public interface IUnityAdsLoadListener {
  void OnUnityAdsAdLoaded(string adUnitId);
  void OnUnityAdsFailedToLoad(string adUnitId, UnityAdsLoadError error, string message);
}

Implement this interface to handle Load results.

OnUnityAdsLoaded
OnUnityAdsLoaded

This callback method handles logic for the ad unit successfully loading.

ParameterDescription
adUnitId
The identifier for the ad unit that loaded content.

OnUnityAdsFailedToLoad
OnUnityAdsFailedToLoad

This callback method handles logic for the ad unit failing to load.

ParameterDescription
adUnitId
The identifier for the ad unit that failed to load.
error

The UnityAdsLoadError that caused the load to fail.

message
A message associated with the error.

IUnityAdsShowListener
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 Show results.

OnUnityAdsShowFailure
OnUnityAdsShowFailure

This callback method handles logic for the ad unit failing to show.

ParameterDescription
adUnitId
The identifier for the ad unit that failed to show.
error

The UnityAdsShowError that caused the show to fail.

message
A message associated with the error.

OnUnityAdsShowStart
OnUnityAdsShowStart

This callback method handles logic for the ad starting to play.

ParameterDescription
adUnitId

The identifier for the ad unit showing the content.

OnUnityAdsShowClick
OnUnityAdsShowClick

This callback method handles logic for the user clicking on the ad.

ParameterDescription
adUnitId

The identifier for the ad unit showing the content.

OnUnityAdsShowComplete
OnUnityAdsShowComplete

This callback method handles logic for the ad finishing.

ParameterDescription
adUnitId
The identifier for the ad unit showing the content.
showCompletionState

Indicates the final state of the ad (whether the ad was skipped or completed).

IUnityAdsListener
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
OnUnityAdsReady

Specify logic for ad content being ready to display through a specified ad unit.

ParameterDescription
adUnitId
The identifier for the ad unit that is ready.

OnUnityAdsDidError
OnUnityAdsDidError

Specify logic for ad content failing to display due to an error.

ParameterDescription
message
A message associated with the error.

OnUnityAdsDidStart
OnUnityAdsDidStart

Specify logic for the player triggering an ad to show.

ParameterDescription
adUnitId

The identifier for the ad unit that is showing content.

OnUnityAdsDidFinish
OnUnityAdsDidFinish

Specify logic for the player watching the ad in its entirety.

ParameterDescription
adUnitId

The identifier for the ad unit that finished showing.

showResult

The resulting user event of the ad showing.