Knowledge base

Android 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

public static void initialize(final Context context, final String gameId, final boolean testMode, final boolean enablePerPlacementLoad, final IUnityAdsInitializationListener initializationListener) 

Initializes the ads service, with a specified Game ID, test mode status, and Ad Unit load setting.

Parameter Description
context The current Android Context.
gameId The platform-specific Unity game identifier for your project, found on the developer dashboard.
initializationListener Optionally enables the SDK with IUnityAdsInitializationListener callbacks (versions 3.7.0 and higher).
testMode Test mode allows you to test your integration without serving live ads. Use true to initialize in test mode.
enablePerPlacementLoad Optionally enables the SDK with the load API lifecycle (versions 3.5.0 and higher).

load

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

Loads ad content for a specified Ad Unit. If you initialized the SDK with enablePerPlacementLoad enabled, 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 collecton of options that modify ad behavior.
listener Optionally loads ad content with IUnityAdsLoadListener callbacks (versions 3.7.0 and higher).

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 higher).

addListener

public static void addListener(IUnityAdsListener listener) 

Adds a listener that will recieve Unity Ads callbacks. Versions 3.1.0 and higher allow you to 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.

BannerView

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

Use this constructor to implement a banner view using an Ad Unit ID and banner 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()

Returns 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

public enum UnityAdsError {
    NOT_INITIALIZED,
    INITIALIZE_FAILED,
    INVALID_ARGUMENT,
    VIDEO_PLAYER_ERROR,
    INIT_SANITY_CHECK_FAIL,
    AD_BLOCKER_DETECTED,
    FILE_IO_ERROR,
    DEVICE_ID_ERROR,
    SHOW_ERROR,
    INTERNAL_ERROR
}

The enumerated reasons for an add to fail.

Interfaces

IUnityAdsInitializationListener

public interface 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

public interface IUnityAdsLoadListener {
    void onUnityAdsAdLoaded(String adUnitId);
    void onUnityAdsFailedToLoad(String adUnitId, UnityAds.UnityAdsLoadError error, String message);
}

Implement this interface to handle UnityAds.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

public interface IUnityAdsShowListener {
    void onUnityAdsShowFailure(String adUnitId, UnityAds.UnityAdsShowError error, String message);
    void onUnityAdsShowStart(String adUnitId);
    void onUnityAdsShowClick(String adUnitId);
    void onUnityAdsShowComplete(String adUnitId, UnityAds.UnityAdsShowCompletionState state);
}

Implement this interface to handle UnityAds.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

public interface IUnityAdsListener
{
    void onUnityAdsReady(String adUnitId);
    void onUnityAdsDidError(UnityAds.UnityAdsError error, String message);
    void onUnityAdsDidStart(String adUnitId);
    void onUnityAdsDidFinish(String adUnitId, FinishState result);
}

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

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

public interface IListener {
    void onBannerLoaded(BannerView bannerAdView);
    void onBannerClick(BannerView bannerAdView);
    void onBannerFailedToLoad(BannerView bannerAdView, BannerErrorInfo errorInfo);
    void onBannerLeftApplication(BannerView bannerView);
}

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

public static abstract class Listener implements IListener {
    @Override
    public void onBannerLoaded(BannerView bannerAdView) {
    }
    @Override
    public void onBannerFailedToLoad(BannerView bannerAdView, BannerErrorInfo errorInfo) {
    }
    @Override
    public void onBannerClick(BannerView bannerAdView) {
    }
    @Override
    public void onBannerLeftApplication(BannerView bannerAdView) {
    }
}

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.
Still need help? Get in touch!
Last updated on 22nd Oct 2021