Unity Ads Android SDK API reference - Kotlin and Java
Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in Kotlin and Java to integrate and control ad behavior in your Android app.
Read time 16 minutesLast updated a day ago
Use this reference for the Unity Ads Android SDK API in Java and Kotlin as you integrate Unity Ads into your Android applications.Before using this API, ensure that you've imported the
class manages the loading and displaying of banner ads.
BannerLoadConfiguration
Encapsulates the options needed to load a
BannerAd
.
Parameter
Description
Required
placementId
The unique identifier for your banner Placement.
Yes
bannerSize
The
BannerSize
of the ad (width and height in pixels).
Yes
adMarkup
Ad markup for bidding scenarios.
No
mediationInfo
Mediation partner information.
No
mediationAdUnitId
Used by mediation for tracking performances.
No
extras
A map of additional key-value parameters.
No
listener
A BannerShowListener to handle banner lifecycle events.
No
val bannerLoadConfiguration = BannerLoadConfiguration.Builder("banner_placement", bannerSize).withAdMarkup("ad_markup").withMediationInfo(mediationInfo).withMediationAdUnitId("mediation_ad_unit_id") .withExtras(mapOf("key" to "value")) .withListener(bannerListener) .build()
Sets the ad markup and returns the builder for chaining.
withMediationInfo(MediationInfo)
mediationInfo
: Mediation partner information.
No
Builder
Sets the mediation info and returns the builder for chaining.
withMediationAdUnitId(String)
mediationAdUnitId
: Used by mediation for tracking performances.
No
Builder
Sets the mediation ad unit ID and returns the builder for chaining.
withExtras(Map<String, String>)
extras
: A map of additional key-value parameters. Calling this multiple times will override the previous value.
No
Builder
Sets the extras map and returns the builder for chaining.
withListener(BannerShowListener)
listener
: A BannerShowListener to handle banner lifecycle events.
No
Builder
Sets the show listener and returns the builder for chaining.
build()
None
No
BannerLoadConfiguration
Creates and returns the
BannerLoadConfiguration
instance with the configured parameters.
val bannerLoadConfiguration = BannerLoadConfiguration.Builder("banner_placement", bannerSize).withAdMarkup("ad_markup").withMediationInfo(mediationInfo).withMediationAdUnitId("mediation_ad_unit_id").withExtras(mapOf("key" to "value")).withListener(bannerListener).build()
BannerLoadConfiguration bannerLoadConfiguration = new BannerLoadConfiguration.Builder("banner_placement", bannerSize).withAdMarkup("ad_markup").withMediationInfo(mediationInfo).withMediationAdUnitId("mediation_ad_unit_id").withExtras(Collections.singletonMap("key", "value")).withListener(bannerListener).build();
load()
Loads a banner ad with the specified BannerLoadConfiguration.
Parameter
Description
Required
configuration
An instance of
BannerLoadConfiguration
containing banner-specific loading options.
Yes
listener
A
BannerLoadListener
that is called when loading is complete, providing either a
BannerAd
instance or an error.
Yes
Returns:
Unit
(void) - This is an asynchronous method that returns immediately. The result is provided through the
BannerLoadListener
callback.
val bannerSize = BannerSize(320, 50)val loadConfig = BannerLoadConfiguration.Builder("banner_placement", bannerSize).build()BannerAd.load(loadConfig, { bannerAd, error -> if (bannerAd != null) { // Banner loaded successfully, you can now add it to your view hierarchy this.bannerAd = bannerAd } else { // Handle load error }})
BannerSize bannerSize = new BannerSize(320, 50);BannerLoadConfiguration loadConfig = new BannerLoadConfiguration.Builder("banner_placement", bannerSize).build();BannerAd.load(loadConfig, (bannerAd, error) -> { if (bannerAd != null) { // Banner loaded successfully, you can now add it to your view hierarchy this.bannerAd = bannerAd; } else { // Handle load error }});
view
A view property that provides access to the banner ad instance. Use this property to insert the banner ad within your app's existing view hierarchy at the desired location.Returns:
View?
(nullable View) - The Android View containing the banner ad, or null if the ad has not been loaded successfully.
// Assuming 'bannerAd' is a loaded BannerAd instance// Assuming 'adPlaceholder' is a ViewGroup (e.g., LinearLayout, FrameLayout) in your layout where you want to display the adbannerAd.view?.let { adPlaceholder.addView(it)}
// Assuming 'bannerAd' is a loaded BannerAd instance// Assuming 'adPlaceholder' is a ViewGroup (e.g., LinearLayout, FrameLayout) in your layout where you want to display the adif (bannerAd.getView() != null) { adPlaceholder.addView(bannerAd.getView());}
BannerView
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.Use
A class containing all the settings for SDK initialization. An instance of this class is created using its
Builder
.
Parameter
Description
Required
gameId
Your unique game identifier from the Unity Ads Monetization dashboard.
Yes
isTestModeEnabled
A boolean that enables test mode. When true, only test ads are shown. Defaults to false.
No
logLevel
Specifies the level of detail for log output. See
LogLevel
. Defaults to INFO.
No
mediationInfo
An object containing information about the mediation partner. See
MediationInfo
.
No
extras
A map of additional key-value parameters for advanced configurations.
No
InitializationConfiguration.Builder
The builder class for creating an
InitializationConfiguration
instance.
Constructor
Builder(gameId: String)
Parameter
Description
Required
gameId
Your unique game identifier from the Unity Ads Monetization dashboard.
Yes
Returns: A new
InitializationConfiguration.Builder
instance.
Builder methods
Method
Parameter
Required
Returns
Description
withTestMode(Boolean)
isTestModeEnabled
: A boolean that enables test mode. When true, only test ads are shown. Defaults to false.
No
Builder
Sets the test mode and returns the builder for chaining.
withLogLevel(LogLevel)
logLevel
: Specifies the level of detail for log output. See
LogLevel
. Defaults to INFO.
No
Builder
Sets the log level and returns the builder for chaining.
withMediationInfo(MediationInfo)
mediationInfo
: An object containing information about the mediation partner.
No
Builder
Sets the mediation info and returns the builder for chaining.
withExtras(Map<String, String>)
extras
: A map of additional key-value parameters for advanced configurations.
No
Builder
Sets the extras map and returns the builder for chaining.
build()
None
No
InitializationConfiguration
Creates and returns the
InitializationConfiguration
instance with the configured parameters.
val config = InitializationConfiguration.Builder("YOUR_GAME_ID").withTestMode(true).withLogLevel(LogLevel.DEBUG).withMediationInfo(mediationInfo).withExtras(mapOf("key" to "value")).build()
InitializationConfiguration config = new InitializationConfiguration.Builder("YOUR_GAME_ID").withTestMode(true).withLogLevel(LogLevel.DEBUG).withMediationInfo(mediationInfo).withExtras(Collections.singletonMap("key", "value")).build();
initialize()
Initializes the Unity Ads SDK with a specified configuration. The
InitializationListener
is called when initialization completes with either success or failure.
Parameter
Description
Required
configuration
The
InitializationConfiguration
object that contains the required settings to initialize the SDK.
No
listener
The
InitializationListener
is called upon completion, indicating success or detailing the reason for failure with an optional error message.
No
Returns:
Unit
(void) - This is an asynchronous method that returns immediately. The result is provided through the
The unique identifier for your ad Placement, found on the Unity Monetization Dashboard.
Yes
adMarkup
Ad markup for bidding scenarios.
No
mediationInfo
Mediation partner information.
No
mediationAdUnitId
Used by mediation for tracking performances.
No
extras
A map of additional key-value parameters.
No
val loadConfiguration = LoadConfiguration.Builder("interstitial_placement").withAdMarkup("ad_markup").withMediationInfo(mediationInfo).withMediationAdUnitId("mediation_ad_unit_id") .withExtras(mapOf("key" to "value")) // Calling this multiple time will override the previous value. .build()
LoadConfiguration loadConfiguration = new LoadConfiguration.Builder("interstitial_placement").withAdMarkup("ad_markup").withMediationInfo(mediationInfo).withMediationAdUnitId("mediation_ad_unit_id") .withExtras(Collections.singletonMap("key", "value")) .build();
LoadConfiguration.Builder
The builder class for creating a
LoadConfiguration
instance.
Constructor
Builder(placementId: String)
Parameter
Description
Required
placementId
The unique identifier for your ad Placement, found on the Unity Monetization Dashboard.
Yes
Returns: A new
LoadConfiguration.Builder
instance.
Builder methods
Method
Parameter
Required
Returns
Description
withAdMarkup(String)
adMarkup
: Ad markup for bidding scenarios.
No
Builder
Sets the ad markup and returns the builder for chaining.
withMediationInfo(MediationInfo)
mediationInfo
: Mediation partner information.
No
Builder
Sets the mediation info and returns the builder for chaining.
withMediationAdUnitId(String)
mediationAdUnitId
: Used by mediation for tracking performances.
No
Builder
Sets the mediation ad unit ID and returns the builder for chaining.
withExtras(Map<String, String>)
extras
: A map of additional key-value parameters. Calling this multiple times will override the previous value.
No
Builder
Sets the extras map and returns the builder for chaining.
build()
None
No
LoadConfiguration
Creates and returns the
LoadConfiguration
instance with the configured parameters.
UnityAdsLoadOptions
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.Use
was the previous class for specifying ad show options.
TokenConfiguration
A class containing the settings for generating a bidding token.
Parameter
Description
Required
adFormat
The AdFormat for which to generate a token (e.g.,
REWARDED
,
INTERSTITIAL
).
Yes
mediationInfo
An object containing information about the mediation partner. See
MediationInfo
.
No
extras
A map of additional key-value parameters.
No
val tokenConfig = TokenConfiguration.Builder(AdFormat.REWARDED).withMediationInfo(mediationInfo).withExtras(extras).build()
TokenConfiguration tokenConfig = new TokenConfiguration.Builder(AdFormat.REWARDED).withMediationInfo(mediationInfo).withExtras(extras).build();
TokenConfiguration.Builder
The builder class for creating a
TokenConfiguration
instance.
Constructor
Builder(adFormat: AdFormat)
Parameter
Description
Required
adFormat
The AdFormat for which to generate a token (e.g.,
REWARDED
,
INTERSTITIAL
,
BANNER
).
Yes
Returns: A new
TokenConfiguration.Builder
instance.
Builder methods
Method
Parameter
Required
Returns
Description
withMediationInfo(MediationInfo)
mediationInfo
: An object containing information about the mediation partner.
No
Builder
Sets the mediation info and returns the builder for chaining.
withExtras(Map<String, String>)
extras
: A map of additional key-value parameters.
No
Builder
Sets the extras map and returns the builder for chaining.
build()
None
Not applicable
TokenConfiguration
Creates and returns the
TokenConfiguration
instance with the configured parameters.
getToken
Fetches a bidding token based on the provided
TokenConfiguration
and passes it to the token listener.
Parameter
Description
Required
configuration
A
TokenConfiguration
object that specifies the ad format, mediation info, and other parameters.
Yes
listener
A listener that is called with the token if it's successfully fetched, or null if an error occurs.
Yes
Returns:
Unit
(void) - This is an asynchronous method that returns immediately. The result is provided through the
TokenListener
callback.
UnityAds.getToken(tokenConfig, listener)
UnityAds.getToken(tokenConfig, listener);
UnityAds
The UnityAds class is a static class that serves as the primary entry point for the SDK. It handles initialization, token retrieval, and provides access to global SDK properties.
Static variables
isInitialized
A boolean property that determines if the Unity Ads SDK is initialized successfully.Returns: true if the Unity Ads SDK has been successfully initialized.
val isInitialized = UnityAds.isInitialized
boolean isInitialized = UnityAds.isInitialized();
version
A string property that returns the current version of the Unity Ads SDK.Returns: The current installed version of Unity Ads SDK.
val sdkVersion = UnityAds.version
String sdkVersion = UnityAds.getVersion();
userIdentifier
A string property that represents a unique ID for each user of your app.Returns: The current value.
UnityAds.userIdentifier = "my-user-id"
UnityAds.userIdentifier = "my-user-id";
Privacy
Use the following methods to set privacy and user consent flags, helping you comply with supported privacy regulations.
setUserConsent()
Displays the user's opt-in choices for personalized ads.
setUserOptOut()
Offers users the option to opt out of data collection and personalized ads.
setNonBehavioral()
Enables the display of contextual (non-personalized) ads.
An interface for handling show lifecycle events for
BannerAd
. This listener is called at various stages during the banner's display lifecycle.
Method signatures
interface BannerShowListener { fun onBannerShown(bannerAd: BannerAd) fun onBannerClicked(bannerAd: BannerAd) fun onBannerFailedToShow(bannerAd: BannerAd, error: UnityAdsError)}
Method
Parameters
Description
onBannerShown
bannerAd
: The
BannerAd
instance that was shown.
Called when the banner ad is successfully shown on screen.
onBannerClicked
bannerAd
: The
BannerAd
instance that was clicked.
Called when the user clicks on the banner ad.
onBannerFailedToShow
bannerAd
: The
BannerAd
instance that failed to show.
error
: The
UnityAdsError
describing the failure.
Called when the banner ad fails to show.
val bannerShowListener = object : BannerShowListener { override fun onBannerShown(bannerAd: BannerAd) { Log.d("UnityAds", "Banner shown") } override fun onBannerClicked(bannerAd: BannerAd) { Log.d("UnityAds", "Banner clicked") } override fun onBannerFailedToShow(bannerAd: BannerAd, error: UnityAdsError) { Log.e("UnityAds", "Banner failed to show: ${error.message}") }}
BannerShowListener bannerShowListener = new BannerShowListener() { @Override public void onBannerShown(BannerAd bannerAd) { Log.d("UnityAds", "Banner shown"); } @Override public void onBannerClicked(BannerAd bannerAd) { Log.d("UnityAds", "Banner clicked"); } @Override public void onBannerFailedToShow(BannerAd bannerAd, UnityAdsError error) { Log.e("UnityAds", "Banner failed to show: " + error.getMessage()); }};
InitializationListener
An interface for receiving callbacks about the status of SDK initialization. This listener is called when the SDK initialization process completes.
Method signature
fun interface InitializationListener { fun onInitializationComplete(error: UnityAdsError?)}
Method
Parameters
Description
onInitializationComplete
error
: The
UnityAdsError
describing the failure, or null if initialization succeeded.
Called when SDK initialization completes. If error is null, initialization was successful.
was the previous callback interface for SDK initialization.
InterstitialLoadListener
An interface for handling the result of loading an
InterstitialAd
. This listener is called when an interstitial ad load request completes, providing either a successfully loaded
InterstitialAd
instance or an error.
Method signature
fun interface InterstitialLoadListener { fun onInterstitialLoaded(interstitialAd: InterstitialAd?, error: UnityAdsError?)}
Method
Parameters
Description
onInterstitialLoaded
interstitialAd
: The loaded
InterstitialAd
instance if successful, or null if loading failed.
error
: The
UnityAdsError
describing the failure, or null if loading succeeded.
Called when the interstitial ad load request completes. Exactly one of the parameters will be non-null.
val interstitialLoadListener = InterstitialLoadListener { interstitialAd, error -> if (interstitialAd != null) { // Interstitial ad loaded successfully this.interstitialAd = interstitialAd // You can now show the ad } else { // Handle load error Log.e("UnityAds", "Interstitial load failed: ${error?.message}") }}
InterstitialLoadListener interstitialLoadListener = (interstitialAd, error) -> { if (interstitialAd != null) { // Interstitial ad loaded successfully this.interstitialAd = interstitialAd; // You can now show the ad } else { // Handle load error Log.e("UnityAds", "Interstitial load failed: " + error.getMessage()); }};
RewardedLoadListener
An interface for handling the result of loading a
RewardedAd
. This listener is called when a rewarded ad load request completes, providing either a successfully loaded
RewardedAd
instance or an error.
Method signature
fun interface RewardedLoadListener { fun onRewardedLoaded(rewardedAd: RewardedAd?, error: UnityAdsError?)}
Method
Parameters
Description
onRewardedLoaded
rewardedAd
: The loaded
RewardedAd
instance if successful, or null if loading failed.
error
: The
UnityAdsError
describing the failure, or null if loading succeeded.
Called when the rewarded ad load request completes. Exactly one of the parameters will be non-null.
val rewardedLoadListener = RewardedLoadListener { rewardedAd, error -> if (rewardedAd != null) { // Rewarded ad loaded successfully this.rewardedAd = rewardedAd // You can now show the ad } else { // Handle load error Log.e("UnityAds", "Rewarded ad load failed: ${error?.message}") }}
RewardedLoadListener rewardedLoadListener = (rewardedAd, error) -> { if (rewardedAd != null) { // Rewarded ad loaded successfully this.rewardedAd = rewardedAd; // You can now show the ad } else { // Handle load error Log.e("UnityAds", "Rewarded ad load failed: " + error.getMessage()); }};
IUnityAdsLoadListener
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.Use
was the previous callback interface for ad show events.
TokenListener
An interface for receiving the result of a
getToken
call. This listener is called when a bidding token request completes.
Method signature
fun interface TokenListener { fun onTokenReady(token: String?)}
Method
Parameters
Description
onTokenReady
token
: The bidding token as a String if successful, or null if token generation failed.
Called when the token request completes. The token should be passed to your mediation partner's SDK for bidding.
val listener = TokenListener { token -> if (token != null) { // Pass the token to your mediation partner's SDK Log.d("UnityAds", "Token received: $token") } else { // Handle token retrieval failure Log.e("UnityAds", "Token retrieval failed") }}
TokenListener listener = token -> { if (token != null) { // Pass the token to your mediation partner's SDK Log.d("UnityAds", "Token received: " + token); } else { // Handle token retrieval failure Log.e("UnityAds", "Token retrieval failed"); }};
onAdExpired
A method available on
InterstitialAd
and
RewardedAd
instances that allows you to register a callback to handle ad expiration events. This callback is triggered when the ad is no longer valid and should not be shown.
Method signature
// On InterstitialAdfun onAdExpired(callback: (InterstitialAd) -> Unit)// On RewardedAdfun onAdExpired(callback: (RewardedAd) -> Unit)
Parameter
Description
callback
(Required) A function that receives the expired ad instance when the ad expires.
Returns:
Unit
(void) - This method registers the callback and returns immediately.
// For InterstitialAdinterstitialAd.onAdExpired { ad -> // Handle ad expiration - load a new ad Log.d("UnityAds", "Interstitial ad expired") // Load a new ad}// For RewardedAdrewardedAd.onAdExpired { ad -> // Handle ad expiration - load a new ad Log.d("UnityAds", "Rewarded ad expired") // Load a new ad}
// For InterstitialAdinterstitialAd.onAdExpired(ad -> { // Handle ad expiration - load a new ad Log.d("UnityAds", "Interstitial ad expired"); // Load a new ad});// For RewardedAdrewardedAd.onAdExpired(ad -> { // Handle ad expiration - load a new ad Log.d("UnityAds", "Rewarded ad expired"); // Load a new ad});
Enums
AdFormat
Enumerated types for different ad formats.
Value
Description
INTERSTITIAL
A full-screen ad shown at natural breaks in the app, which can be skipped after a few seconds.
REWARDED
A full-screen ad that users opt-in to watch in exchange for an in-app reward.
BANNER
An ad that occupies a portion of the screen, typically at the top or bottom.
LogLevel
Enumerated types for different log verbosity levels.
Value
Description
DISABLED
No logs related to Unity Ads should be printed.
INFO
Default level. Shows standard integration and lifecycle messages.
DEBUG
Shows detailed logs for debugging purposes.
ERROR
Essential errors from init/load/show operations, and critical failures to which a developer must pay attention.
ShowFinishState
Enumerated types describing the final state of an ad after it has been shown.
Value
Description
SKIPPED
The user skipped the ad before it finished.
COMPLETED
The ad was watched to completion. For
RewardedAd
, this state triggers the reward.
UnityAds.UnityAdsShowCompletionState
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.Use