Android (Java) API reference

Overview

This article documents API classes for the following namespaces:

• UnityAds
• UnityBanners
• UnityMonetization
• UnityPurchasing

For a comprehensive integration guide, click here.

UnityAds

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

import com.unity3d.ads.UnityAds;

Methods

initialize

Initializes the Unity Ads service with a specified Game ID and test mode status.

public static void initialize (final Activity activity,
                               final String gameId, 
                               final IUnityAdsListener listener, 
                               final boolean testMode, 
                               final boolean enablePerPlacementLoad)

Parameter	Data type	Description
activity	Activity	The current activity of the Android device calling the app.
gameId	String	The Unity Game ID for your Project, located in the developer dashboard.
listener	IUnityAdsListener	A listener for IUnityAdsListener callbacks.
testMode	boolean	When set to true, only test ads display.
enablePerPlacementLoad	boolean	When set to true, this parameter allows you to load content for a specific Placement prior to displaying it. Please review the load method documentation before enabling this setting.

You can check the initialization status with the following function:

public static boolean isInitialized ()

You can check whether the current platform is supported by the SDK with the following function:

public static boolean isSupported ()

load

Loads ad content for a specified Placement, allowing for more accurate fill request reporting that is consistent with the standards of most mediation providers. If you initialized the SDK with enablePerPlacementLoad enabled, you must call load before calling show.

Note The load API is in closed beta and available upon invite only. If you would like to be considered for the beta, please contact Unity Ads.

public static void load (final String placementId) {
    UnityAdsImplementation.load (placementId);
}

show

Shows content in the specified Placement, if it is ready.

public static void show (final Activity activity, final String placementId)

Parameter	Data type	Description
activity	Activity	The current activity of the Android device calling the app.
placementId	String	The Placement ID, located on the developer dashboard.

You can check whether an ad is ready to be shown for the specified Placement by calling:

public static boolean isReady (String placementId)

addListener

Adds an active listener for IUnityAdsListener callbacks. SDK versions 3.1+ allow you to register multiple listeners. This is especially helpful for mediation customers.

public static void addListener (IUnityAdsListener listener) 

removeListener

Allows you to remove an active listener.

public static void removeListener (IUnityAdsListener listener) 

setListener

Sets the current listener for IUnityAdsListener callbacks. Use this if you only ever use one listener.

public static void getListener ()

Note: setListener is a deprecated method. Unity recommends using addListener instead.

getListener

Retrieves the current listener for IUnityAdsListener callbacks. Returns the first listener added.

public static void getListener () 

Note: getListener is a deprecated method.

setDebugMode

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

public static void setDebugMode (boolean debugMode)

You can check the current status for debug logging from the SDK by calling:

public static boolean getDebugMode ()

Interfaces

IUnityAdsListener

An interface for handling various states of an ad. Implement this listener in your script to define logic for rewarded ads. The interface has the following methods:

public interface IUnityAdsListener {
    void onUnityAdsReady (String placementId);
    void onUnityAdsError (UnityAds.UnityAdsError error, String message);
    void onUnityAdsStart (String placementId);
    void onUnityAdsFinish (String placementId, UnityAds.FinishState result);
}

Note: Unity recommends implementing all of these methods in your code, even if you don’t use them all.

Interface method	Description
onUnityAdsReady	Handles logic for ad content being ready to display through a specified Placement.
onUnityAdsStart	Handles logic for the player triggering an ad to play.
OnUnityAdsFinish	Handles logic for an ad finishing. Define conditional behavior for different finish states by accessing the FinishState result from the listener (documented below). For example: void OnUnityAdsDidFinish (string placementId, ShowResult showResult) {   if (showResult == ShowResult.Finished) {     // Reward the user for watching the ad to completion.   } else if (showResult == ShowResult.Skipped) {     // Do not reward the user for skipping the ad.   } else if (showResult == ShowResult.Failed) {     Debug.LogWarning (“The ad did not finish due to an error.);   } }
onUnityAdsError	Handles logic for ad content failing to display because of an error.

Enums

FinishState

The enumerated states of the end-user’s interaction with the ad. The SDK passes this value to the onUnityAdsFinish callback after the ad completes.

enum UnityAds.FinishState

Value	Description
ERROR	Indicates that the ad failed to complete due to a Unity error.
SKIPPED	Indicates that the user skipped the ad.
COMPLETED	Indicates that the user successfully finished watching the ad.

PlacementState

The enumerated states of a Unity Ads Placement.

enum UnityEngine.Advertisements.PlacementState

Value	Description
READY	The Placement is ready to show ads.
NOT_AVAILABLE	The Placement is not available.
DISABLED	The Placement was disabled.
WAITING	The Placement is waiting to be ready.
NO_FILL	The Placement has no advertisements to show.

Retrieve the PlacementState value with the following function:

public static PlacementState getPlacementState (String placementId)

UnityAdsError

The enumerated causes of a Unity Ads error.

Value	Description
NOT_INITIALIZED	The Unity Ads service is currently uninitialized.
kINITIALIZE_FAILED	An error occurred in the initialization process.
INVALID_ARGUMENT	Unity Ads initialization failed due to invalid parameters.
VIDEO_PLAYER_ERROR	An error occurred due to the video player failing.
INIT_SANITY_CHECK_FAIL	Initialization of the Unity Ads service failed due to an invalid environment.
AD_BLOCKER_DETECTED	An error occurred due to an ad blocker.
FILE_IO_ERROR	An error occurred due to inability to read or write a file.
DEVICE_ID_ERROR	An error occurred due to a bad device identifier.
SHOW_ERROR	An error occurred when attempting to show an ad.
INTERNAL_ERROR	An internal Unity Ads service error occurred.

UnityBanners

Use this namespace to implement banner ads.

import com.unity3d.services.banners.UnityBanners;

Methods

loadBanner

The basic method for requesting an ad for the banner.

public static void loadBanner (final Activity activity, final String placementId)

destroy

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

public static void destroy ()

setBannerPosition

Sets the position of the banner ad, using the BannerPosition enum.

public static void setBannerPosition (BannerPosition position)

Interfaces

IUnityBannerListener

Implement this interface to handle various banner states. The listener includes the following methods:

public interface IUnityBannerListener {
    void onUnityBannerLoaded (String placementId, View view);
    void onUnityBannerUnloaded (String placementId);
    void onUnityBannerShow (String placementId);
    void onUnityBannerClick (String placementId);
    void onUnityBannerHide (String placementId);
    void onUnityBannerError (String message);
}

Note: Unity recommends implementing all of these methods in your code, even if you don’t use them all.

Interface method	Description
onUnityBannerLoaded	Called when the Unity banner finishes loading an ad. The view parameter references the banner that should be inserted into the view hierarchy.
onUnityBannerUnloaded	Called when ad content is unloaded from the banner, and references to its view should be removed.
onUnityBannerShow	Called when the Unity banner is shown for the first time and visible to the user.
onUnityBannerClick	Called when the Unity banner is clicked.
onUnityBannerHide	Called when the Unity banner is hidden.
onUnityBannerError	Called when an error occurs showing the banner.

Enums

BannerPosition

The enumerated positions you can set as an anchor for banner ads.

public enum BannerPosition {
    TOP_LEFT,
    TOP_CENTER,
    TOP_RIGHT,
    BOTTOM_LEFT,
    BOTTOM_CENTER,
    BOTTOM_RIGHT,
    CENTER
}

UnityMonetization

Use this namespace to implement ads for use with Personalized Placements.

import com.unity3d.services.monetization.UnityMonetization;

Methods

initialize

Initializes Unity Ads in your game at run time. To avoid errors, initialization should occur early in the game’s run-time lifecycle, preferably at boot. Initialization must occur prior to showing ads.

public static void initialize (Activity activity, 
                               String gameId, 
                               IUnityMonetizationListener listener, 
                               boolean testMode);

The activity parameter is the current Android Activity. The gameID parameter is the Game ID for your Project found on the developer dashboard. The listener parameter is the listener for IUnityMonetizationListener callbacks (documented below). The testMode parameter indicates whether the game is in test mode. When testMode is true, you will only see test ads. When testMode is false, you will see live ads. It is important to use test mode prior to launching your game, to avoid being flagged for fraud.

You can check whether the service is initialized by calling:

Checks whether a PlacementContent object is ready for the given Placement. Returns true if content is ready, and false if it isn’t.

public static boolean isInitialized ();

isReady

Checks whether a PlacementContent object is ready for the given Placement. Returns true if content is ready, and false if it isn’t.

public static boolean isReady (String placementId);

setListener

Sets the IUnityMonetizationListener listener for PlacementContent callback events.

public static void setListener (IUnityMonetizationListener listener);

getListener

Returns the current IUnityMonetizationListener listener for PlacementContent callback events.

public static IUnityMonetizationListener getListener ();

Interfaces

IUnityMonetizationListener

An interface for handling various states of a PlacementContent object. The interface has the following methods:

public interface IUnityMonetizationListener extends IUnityServicesListener {
    void onPlacementContentReady (String placementId, 
                                  PlacementContent placementcontent);
    void onPlacementContentStateChange (String placementId, 
                                        PlacementContent placementcontent, 
                                        UnityMonetization.PlacementContentState previousState, 
                                        UnityMonetization.PlacementContentState newState);
}

Note: Unity recommends implementing all of these methods in your code, even if you don’t use them all.

Interface method	Description
onPlacementContentReady	This function notifies you that a PlacementContent object is ready for a given Placement and ready to show.
onPlacementContentChanged	This function notifies you when the readied PlacementContent object’s status has changed due to a refresh.

Example IUnityMonetizationListener implementation:

private class UnityMonetizationListener implements IUnityMonetizationListener {

    @Override
    public void onPlacementContentReady (String placementId, PlacementContent placementContent) {
        // Check the Placement ID to determine behavior
        switch (placementId) {
            case "mixedPlacement":
                if (placementContent instanceof PromoAdPlacementContent) {
                    PromoAdPlacementContent promoPlacementContent = ((PromoAdPlacementContent) placementContent)
                    // Promo content is ready, prepare Promo display
                } else if (placementContent instanceof ShowAdPlacementContent) {
                    ShowAdPlacementContent adPlacementContent = ((ShowAdPlacementContent) placementContent);
                    // Ad content is ready, prepare video ad display
                }
                break;
            case "rewardedVideo":
                if (placementContent instanceof ShowAdPlacementContent) {
                    ShowAdPlacementContent adPlacementContent = ((ShowAdPlacementContent) placementContent);
                    if (adPlacementContent.isRewarded ()) {
                        // Rewarded content is ready, prepare content for display and implement reward handlers 
                    }
                }
                break;
        }
    }

    @Override
    public void onPlacementContentStateChange (String placementId, PlacementContent placementContent, UnityMonetization.PlacementContentState previousState, UnityMonetization.PlacementContentState newState) {
    }
}

IShowAdListener

Implement this interface for ShowAdPlacementContent objects. The interface has the following methods:

Interface method	Description
void onAdStarted (String placementId);	Called when the video ad starts.
void onAdFinished(String placementId, UnityAds.FinishState withState);	Called when the video ad finishes. Use this callback method to evaluate the ad's FinishState and act accordingly.

Classes

PlacementContent

A class representing monetization content that your Placement can display.

Associated methods:

Method	Description
public static PlacementContent getPlacementContent (String placementId);	Returns the PlacementContent object that is ready for the given Placement. Returns null if no content is ready.
public static <T extends PlacementContent> T getPlacementContent (String placementId, Class<T> asClass);	Extends the getPlacementContent function to cast the returned PlacementContent as a specific type. The asClass parameter represents the type you wish to cast to. If the returned content is of a different type, it returns null.
public boolean isReady ();	This function returns true if the PlacementContent object is ready to display, and false if it isn’t.
public String getType ();	This function returns the type of PlacementContent available to display. The following string values are valid: SHOW_AD refers to video ad content using the ShowAdPlacementContent class extension. PROMO_AD refers to IAP Promo content using the PromoAdPlacementContent class extension. NO_FILL refers to a lack of PlacementContent available for the specified Placement.

RewardablePlacementContent

Extends the PlacementContent class with functionality to support rewarded content.

Associated methods:

Method	Description
public boolean isRewarded ();	This function returns true if the PlacementContent is rewarded, and false if it isn’t.

ShowAdPlacementContent

Extends the RewardablePlacementContent class with functionality to support video ad content.

Associated methods:

Method	Description
public void show (Activity activity, IShowAdListener listener);	This function displays the available ShowAdPlacementContent. Implement an IShowAdListener interface to define how this function responds to each ad FinishState.

PromoAdPlacementContent

Extends the ShowAdPlacementContent class, providing functionality for IAP Promo content. For more information, see documentation on Native Promos.

Enums

PlacementContentState

The enumerated states of a Placement.

Value	Description
READY	PlacementContent is available to show.
NOT_AVAILABLE	PlacementContentState is unavailable. Either the SDK is not properly initialized, or the respective Placement is not configured to display monetization content.
DISABLED	The specified Placement is disabled. You can enable the Placement via the developer dashboard.
WAITING	The Placement is not yet ready, but it will be in the future. This is likely due to caching.
NO_FILL	The Placement is properly configured, but there are currently no ads available to show.

FinishState

An enum representing the final state of an ad when finished. Use it to handle reward cases.

Value	Description
COMPLETED	The player viewed the ad in its entirety.
SKIPPED	The player skipped the ad before it played in its entirety.
ERROR	The ad failed to load.

UnityPurchasing

This class manages purchasing adapters, which are interfaces for the SDK to retrieve the information it needs from your custom IAP implementation.

public class UnityPurchasing {    
    public static void setAdapter (IPurchasingAdapter adapter);
    public static IPurchasingAdapter getAdapter ();
}

Interfaces

IPurchasingAdapter

An interface for implementing a custom purchasing solution that's compatible with IAP Promo.

public interface IPurchasingAdapter {
    void retrieveProducts (IRetrieveProductsListener listener);
    void onPurchase (String productID, ITransactionListener listener, Map<String, Object> extras);
}

Interface method	Description
void retrieveProducts (IRetrieveProductsListener listener);	The SDK calls this to retrieve the list of available Products. Use the IRetrieveProductsListener interface to register your Product list.
void onPurchase (String productID, ITransactionListener listener, Map<String, Object> extras);	The SDK calls this when a user clicks the buy button for a promotional asset. Use the ITransactionListener interface to listen for the transaction result. Unity passes the purchased Product’s ID to your in-app purchasing system. The purchase’s success or failure handling depends on your in-app purchasing implementation.

Example of an implemented retrieveProducts function:

@Override
public void retrieveProducts (IRetrieveProductsListener listener) {
    listener.onProductsRetrieved (Arrays.asList (Product.newBuilder ()
        .withProductId ("100BronzeCoins")     
        .withLocalizedTitle ("100 Bronze Coins")
        .withLocalizedPriceString ("$1.99")
        .withLocalizedPrice (1.99)
        .withIsoCurrencyCode ("USD")
        .withLocalizedDescription ("100 Bronze Coins at a new low price!")
        .withProductType ("Consumable")
        .build ()));
}

Example of an implemented onPurchase function:

@Override
public void onPurchase (String productID, ITransactionListener listener, Map<String, Object> extras) {
    thirdPartyPurchasing.purchase (productId); // Generic developer purchasing function

    // If purchase succeeds:
    listener.onTransactionComplete (TransactionDetails.newBuilder ()
        .withProductId ("100BronzeCoins")

        .withTransactionId ("ABCDEFG")
        .withReceipt ("receipt":"{\"data\": \"{\"Store\": \"fake\", \"TransactionID\": \"ce7bb1ca-bd34-4ffb-bdee-83d2784336d8\", \"Payload\": \"{ \\\"this\\\": \\\"is a fake receipt\\\"}\"}\"}")
        .withPrice (1.99)

        .withIsoCurrency ("USD")

        .build());

    // If purchase fails:
    listener.onTransactionError (TransactionError.NETWORK_ERROR, "No Network Connection");
}

IRetrieveProductsListener

Registers your IAP products with the SDK. Your implementation must convert your IAP products into UnityMonetization.Product objects. This requires a minimum of the following properties for each Product:

• productID
• localizedPriceString
• productType
• isoCurrencyCode
• localizedTitle.

public interface IRetrieveProductsListener {
    void onProductsRetrieved (List<Product> availableProducts);
}

ITransactionListener

An interface that passes a transaction's result back to your purchasing system, in the form of a TransactionDetails or TransactionErrorDetails object.

Interface method	Description
void onTransactionComplete (TransactionDetails details);	Your custom game logic for handling a successful transaction. The function takes a TransactionDetails object, which details the specifics of a transaction.
void onTransactionError (TransactionErrorDetails details);	Your custom game logic for handling a failed transaction. The function takes a TransactionError object, which identifies the source of transaction failure.

NativePromoAdapter

This interface provides access methods for handling user interaction with promotional assets. Use these methods to pass in your custom assets and define expected behavior. Pass a PromoAdPlacementContent object through the NativePromoAdapter function to create a new adapter. For example:

final NativePromoAdapter nativePromoAdapter = new NativePromoAdapter (placementContent);

Implement this delegate with the following methods:

Delegate method	Description
public void onShown (NativePromoShowType type);	Call this function when the Promo is shown. It should include your custom method for displaying promotional assets. You can pass a NativePromoShowType enum value to reference the preview type of your Promo asset.
public void onClosed ();	Call this function when the player dismisses the Promo offer.
public void onClicked ()	Call this function when the player clicks the button to purchase the Product. It should initiate the purchase flow.

Classes

PromoAdPlacementContent

Extends the ShowAdPlacementContent class, providing functionality for IAP Promo content. This class has the following properties:

Property	Description
PromoMetaData	Contains information for a PromoAdPlacementContent object passed through the adapter.

Product

An IAP product converted into an object that the SDK can use for optimizing monetization.

Set the following fields on the builder using the public static Builder newBuilder() method, then the public Product build() method to construct the final Product object.

Builder method	Param type	Description
withProductId	String	An internal reference ID for the Product.
withLocalizedTitle	String	A consumer-facing name for the Product, for store UI purposes.
withLocalizedPriceString	String	A consumer-facing price string, including the currency sign, for store UI purposes.
withLocalizedPrice	Double	The internal system value for the Product’s price.
withIsoCurrencyCode	String	The ISO code for the Product’s localized currency.
withLocalizedDescription	String	A consumer-facing Product description, for store UI purposes.
withProductType	String	Unity supports "Consumable", "Non-consumable", and "Subscription" Product Types.

Use the following functions to retrieve Product properties:

Method	Description
public String getProductId ();	Retrive the Product ID.
public String getLocalizedTitle ();	Retrive the localized Product title.
public String getLocalizedPriceString ();	Retrive the localized Product price string.
public double getLocalizedPrice ();	Retrive the localized Product price value.
public String getIsoCurrencyCode ();	Retrive the Product price's currency code.
public String getLocalizedDescription ();	Retrive the localized Product description.
public String getProductType ();	Retrive the Product type.

For more details on Product properties, see documentation on Defining Products.

TransactionDetails

An IAP transaction receipt converted into an object that the SDK can use for optimizing monetization.

Set the following fields on the builder using the public static Builder newBuilder () method, then the public TransactionDetails build () method to construct the final Product object.

Builder method	Param type	Description
withProductId	String	An internal reference ID for the Product.
withTransactionId	String	An internal reference ID for the transaction.
withReceipt	String	The JSON fields from the INAPP_PURCHASE_DATA detailing the transaction. Encode the receipt as a JSON object containing Store, TransactionID, and Payload.
withPrice	BigDecimal	The internal system value for the Product’s price.
withIsoCurrency	String	The ISO code for the Product’s localized currency.

Use the following functions to retrieve Product properties:

public String getProductId (); public String getTransactionId (); public String getReceipt (); public BigDecimal getPrice (); public String getCurrency ();

Enums

TransactionError

The enumerated reasons for a transaction failure.

public enum TransactionError {
    ITEM_UNAVAILABLE
    NETWORK_ERROR
    NOT_SUPPORTED
    SERVER_ERROR
    UNKNOWN_ERROR
    USER_CANCELLED
}

NativePromoShowType

The enumerated display types of a Native Promo asset.

Value	Description
FULL	Indicates a full promotional view.
PREVIEW	Indicates a minimized view that can expand to display the full Promo.