Skip to content

api android

Jump to bottom
Jesse Reiter-Skolnick edited this page May 23, 2019 · 7 revisions

/*
Title: Android API reference Description:
Sort: 5 */

Overview

This article documents API for the following namespaces:

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;

initialize

Initializes the 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)
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 (documented below).
testMode boolean When set to true, only test ads display.

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 ()

setDebugMode

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

public static void setDebugMode (boolean debugMode)

getDebugMode

Returns the current status for debug logging from the SDK.

public static boolean getDebugMode ()

isReady

Returns whether an ad is ready to be shown for the specified Placement.

public static boolean isReady (String 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.

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)

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.

onUnityAdsReady

An IUnityAdsListener method that handles logic for ad content being ready to display through a specified Placement. For example:

void onUnityAdsReady (String placementId) {
    Advertisement.show (activity, placementId);
}

onUnityAdsStart

An IUnityAdsListener method that handles logic for the player triggering an ad to play. For example:

void onUnityAdsStart (String placementId) {
    Debug.Log (“The ad started playing.”);
}

OnUnityAdsFinish

An IUnityAdsListener method that 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

An IUnityAdsListener method that handles logic for ad content failing to display because of an error. For example:

void onUnityAdsError (UnityAds.UnityAdsError error, String errorMessage) {
    Debug.LogWarning (errorMessage);
}

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.

addListener

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 ()

getListener

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

public static void getListener ()

Back to top

UnityBanners

Class for implementing banner ads.

import com.unity3d.services.banners.UnityBanners;

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.

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.

setBannerPosition

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

public static void setBannerPosition (BannerPosition position)

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
}

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 ()

Back to top

UnityMonetization

Use this namespace to implement Personalized Placements.

import com.unity3d.services.monetization.UnityMonetization;

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.

IUnityMonetizationListener

An interface for handling various states of ad content. The interface has the following methods:

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) {
    }
}

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 ();

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);

PlacementContent

An object representing monetization content that your Placement can display.

getPlacementContent

Returns the PlacementContent object that is ready for the given Placement. Returns null if no content is ready.

public static PlacementContent getPlacementContent (String placementId);

You can extend this function to cast the returned PlacementContent as a specific type. If the returned content is of a different type, it returns null.

public static <T extends PlacementContent> T getPlacementContent (String placementId, Class<T> asClass);

The asClass parameter represents the type you wish to cast to.

isReady

This function returns true if the PlacementContent object is ready to display, and false if it isn’t.

public boolean isReady ();

getType

This function returns the type of PlacementContent available to display.

public String getType ();

The following string values are valid:

String value Description
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.

isRewarded

This function returns true if the PlacementContent is rewarded, and false if it isn’t.

public boolean isRewarded ();

ShowAdPlacementContent

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

show

This function displays the available ShowAdPlacementContent. Implement an IShowAdListener interface to define how this function responds to each ad FinishState.

public void show (Activity activity, IShowAdListener listener);

IShowAdListener

Implement this interface to provide the onAdsFinished callback method for a video ad’s FinishState.

onAdsFinished

Implement this method to provide logic for handling whether the ad was completed, skipped, or errored out.

void onAdFinished (String placementId, UnityAds.FinishState withState);
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.

Example onAdsFinished implementation:

@Override
public void onAdFinished (String s, UnityAds.FinishState finishState) {
    Log.d ("PlacementId: " + s + " " + finishState);

    if (finishState == UnityAds.FinishState.COMPLETED) {
        if (s.equals (rewardedPlacementId)) {
            // Reward the player here.
        }
    } else if (finishState == UnityAds.FinishState.SKIPPED) {
        // Optionally implement skipped logic
    } else if (finishState == UnityAds.FinishState.ERROR) {
        // Optionally attempt to retrieve another ad
    }
}

PromoAdPlacementContent

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

Back to top

Clone this wiki locally