Documentation

Support

Unity Ads Monetization

Android developer monetization guide

iOS developer monetization guide

Privacy consent setup

Unity Ads Monetization

Unity Ads Android SDK API reference

Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in Java to integrate and control ad behavior in your Android app.
Read time 6 minutesLast updated 4 hours ago
This article contains the following API documentation: Classes Enums Interfaces

Classes

UnityAds

Use this namespace to implement interstitial ad content, such as rewarded or non-rewarded video, 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

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

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)

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

public String getPlacementId()
Returns the ad unit ID for the Banner ad unit.

getSize

public UnityBannerSize getSize()
The 
size
 of the banner.

setListener

public void setListener(IListener listener)
Sets the active listener for the banner.

getListener

public IListener getListener()
Retrieves the active listener for the banner.

load

public void load()
The basic method for requesting an ad for the banner.

destroy

public void destroy()
Call this method to remove the banner from the view hierarchy when you're no longer using it.

UnityBannerSize

public UnityBannerSize(int width, int height)
Use this class to define the height and width of a banner object.

getWidth

public int getWidth()
Returns the width in pixels of the banner object.

getHeight

public int getHeight()
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

...
The enumerated reasons for an add to fail.

Interfaces

IUnityAdsInitializationListener

void onInitializationComplete();
void onInitializationFailed(UnityAds.UnityAdsInitializationError error, String message);
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

void onUnityAdsAdLoaded(String placementId);
void onUnityAdsFailedToLoad(String placementId, UnityAds.UnityAdsLoadError error, String message);
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

void onUnityAdsShowFailure(String placementId, UnityAds.UnityAdsShowError error, String message);
void onUnityAdsShowStart(String placementId);
void onUnityAdsShowClick(String placementId);
UnityAds.UnityAdsShowCompletionState state;
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.

onUnityAdsReady

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

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

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

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();
void onBannerLoaded(BannerView bannerAdView);
void onBannerShown(BannerView bannerAdView);
void onBannerClick(BannerView bannerAdView);
void onBannerFailedToLoad(BannerView bannerAdView, BannerErrorInfo errorInfo);
void onBannerLeftApplication(BannerView bannerView);

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.