Unity Ads Android SDK API reference

This article contains the following API documentation:

Classes

Enums

Interfaces

Classes

UnityAds

Use this namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.

initialize

initialize(final Context context, final String gameId, final boolean testMode, final IUnityAdsInitializationListener initializationListener)

Initializes the ads service, with a specified Game ID, test mode status, and initialization listener.

Parameter

Description

context

The current Android Context.

gameId

The platform-specific Unity game identifier for your project, found on the Unity Ads Monetization 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

public static void load(final String adUnitId, final UnityAdsLoadOptions loadOptions, final IUnityAdsLoadListener listener)

Loads ad content for a specified Ad Unit. You must call load before calling show.

Parameter

Description

adUnitId

The identifier for the Ad Unit you want to load with ad content.

loadOptions

A collection of options that modify ad behavior.

listener

Optionally loads ad content with IUnityAdsLoadListener callbacks (versions 3.7.0 and later).

show

public static void show(final Activity activity, final String adUnitId, final UnityAdsShowOptions options, final IUnityAdsShowListener showListener)

Displays loaded ad content in a specified Ad Unit.

Parameter

Description

activity

The current Android Activity.

adUnitId

The identifier for the Ad Unit you want to show.

options

A collection of options modifying ad behavior.

showListener

Optionally shows content with IUnityAdsShowListener callbacks (versions 3.7.0 and later).

addListener

Removed in SDK version 4.0. For more information, refer to deprecated API classes.

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

listener

A listener for Unity Ads callbacks.

removeListener

Removed in SDK version 4.0. For more information, refer to deprecated API classes.

public static void removeListener(IUnityAdsListener listener)

Removes an active IUnityAdsListener.

Parameter

Description

listener

A listener for Unity Ads callbacks.

getVersion

public static String getVersion()

Returns the current Ads SDK version.

getPlacementState

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.

setDebugMode

public static void setDebugMode(boolean debugMode)

Controls the amount of logging output from the SDK. Set to true for more robust logging.

getDebugMode

public static boolean getDebugMode()

Returns true if the SDK is in debug mode.

isInitialized

public static boolean isInitialized()

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

isSupported

public static bool isSupported()

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

UnityAdsLoadOptions

public class UnityAdsLoadOptions extends UnityAdsBaseOptions

This class contains optional metadata to include with the load method. Customers using header bidding in third-party mediation should use this in cases where a bidder from the Unity network wins the ad auction.

setAdMarkup

public void setAdMarkup(String adMarkup)

This method takes the ad markup returned from the bidder service. When a bidder from Unity's ad network wins a header bidding auction, the Unity Ads SDK receives ad markup from the mediated exchange. The ad markup string contains information needed for Unity to load and show the ad.

setObjectId

public void setObjectId(String objectId)

This method sets the loaded ad object ID as the ad object ID to show.

BannerView

public BannerView(Activity activity, String adUnitId, UnityBannerSize size)

String mObjectId = UUID.randomUUID().toString(); UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions(); loadOptions.setAdMarkup(markup); loadOptions.setObjectId(mObjectId); UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Parameter

Description

activity

The current Android Activity.

adUnitId

The identifier for the Ad Unit you want to show.

size

The size of the banner object.

getPlacementId

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Returns the Ad Unit ID for the Banner Ad Unit.

getSize

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

The size of the banner.

setListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Sets the active listener for the banner.

getListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Retrieves the active listener for the banner.

load

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

The basic method for requesting an ad for the banner.

destroy

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Call this method to remove the banner from the view hierarchy when you’re no longer using it.

UnityBannerSize

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Use this class to define the height and width of a banner object.

getWidth

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Returns the width in pixels of the banner object.

getHeight

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Returns the height in pixels of the banner object.

Enums

PlacementState

The enumerated states of an Ad Unit.

Value

Description

READY

The Ad Unit is ready to show ads.

NOT_AVAILABLE

The Ad Unit is not available.

DISABLED

The Ad Unit has been disabled.

WAITING

The Ad Unit is waiting to be ready.

NO_FILL

The Ad Unit has no advertisements to show.

FinishState

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

ERROR

Indicates that the ad failed to complete due to a Unity service error.

SKIPPED

Indicates that the user skipped the ad.

COMPLETED

Indicates that the user successfully finished watching the ad.

UnityAdsInitializationError

The enumerated reasons for SDK initialization to fail.

Value

Description

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.

UnityAdsShowCompletionState

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.

UnityAdsLoadError

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.

UnityAdsShowError

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.

UnityAdsError

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

The enumerated reasons for an add to fail.

Interfaces

IUnityAdsInitializationListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Implement this interface to handle initialize results.

onInitializationComplete

This callback method handles logic for the SDK successfully initializing.

onInitializationFailed

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.

IUnityAdsLoadListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Implement this interface to handle load results.

onUnityAdsAdLoaded

This callback method handles logic for the Ad Unit successfully loading.

Parameter

Description

adUnitId

The identifier for the Ad Unit that loaded content.

onUnityAdsFailedToLoad

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.

IUnityAdsShowListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Implement this interface to handle show results.

onUnityAdsShowFailure

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.

onUnityAdsShowStart

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

Parameter

Description

adUnitId

The identifier for the Ad Unit showing the content.

onUnityAdsShowClick

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

Parameter

Description

adUnitId

The identifier for the Ad Unit showing the content.

onUnityAdsShowComplete

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.

IUnityAdsListener

Removed in SDK version 4.0. For more information, refer to deprecated API classes.

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Implement this interface to handle various states of an ad. Implement this listener in your script to define logic for rewarded ads.

onUnityAdsReady

Removed in SDK version 4.0. For more information, refer to deprecated API classes.

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.

onUnityAdsDidError

Removed in SDK version 4.0. For more information, refer to deprecated API classes.

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

Parameter

Description

error

The error that caused the ad to fail.

message

A message associated with the error.

onUnityAdsDidStart

Removed in SDK version 4.0. For more information, refer to deprecated API classes.

Specify logic for the player triggering an ad to show.

Parameter

Description

adUnitId

The identifier for the Ad Unit that is showing the ad.

OnUnityAdsDidFinish

Removed in SDK version 4.0. For more information, refer to deprecated API classes.

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

Parameter

Description

adUnitId

The identifier for the Ad Unit that finished showing.

result

The resulting user event of the ad showing.

IListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

This interface grants access to banner lifecycle events. In addition, you can implement the following override methods:

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

onBannerLoaded

This callback fires when the banner finishes loading an ad. The view parameter references the banner that should be inserted into the view hierarchy.

Parameter

Description

bannerAdView

The banner object that loaded.

onBannerClick

This callback fires when the banner is clicked.

Parameter

Description

bannerAdView

The banner object that loaded.

onBannerError

This callback fires when an error occurs showing the banner.

Parameter

Description

bannerAdView

The banner object that loaded.

errorInfo

A class containing information about the banner load error.

onBannerLeftApplication

This callback fires when the banner links outside the application.

Parameter

Description

bannerAdView

The banner object that loaded.

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.