# 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.

This article contains the following API documentation:

**Classes**

* [`UnityAds`](#unityads)
* [`UnityAdsLoadOptions`](#unityadsloadoptions)
* [`BannerView`](#bannerview)
* [`UnityBannerSize`](#unitybannersize)

**Enums**

* [`PlacementState`](#placementstate)
* [`FinishState`](#finishstate)
* [`UnityAdsInitializationError`](#unityadsinitializationerror)
* [`UnityAdsLoadError`](#unityadsloaderror)
* [`UnityAdsShowError`](#unityadsshowerror)
* [`UnityAdsShowCompletionState`](#unityadsshowcompletionstate)
* [`UnityAdsError`](#unityadserror)

**Interfaces**

* [`IUnityAdsInitializationListener`](#iunityadsinitializationlistener)
* [`IUnityAdsLoadListener`](#iunityadsloadlistener)
* [`IUnityAdsShowListener`](#iunityadsshowlistener)

## Classes

### UnityAds

Use this namespace to [implement interstitial ad content](/monetization/sdk-integration/android-sdk/interstitial-ads.md), such as rewarded or non-rewarded video, or banner ads.

#### initialize

```java
initialize(final Context context, final String gameId, final boolean testMode, final IUnityAdsInitializationListener initializationListener)
```

Initializes the ads service, with a specified Game ID, [test mode](/monetization/sdk-integration/android-sdk/test-integration.md) status, and initialization listener.

| Parameter                | Description                                                                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`                | The current Android [`Context`](https://developer.android.com/reference/android/content/Context).                                                    |
| `gameId`                 | The platform-specific Unity game identifier for your project, found on the [Unity Ads Monetization dashboard](https://cloud.unity.com/monetization). |
| `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`](#iunityadsinitializationlistener) callbacks (versions 3.7.0 and later).          |

#### load

```java
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`](#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`](#iunityadsloadlistener) callbacks (versions 3.7.0 and later). |

#### show

```java
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`](https://developer.android.com/reference/android/app/Activity).                       |
| `adUnitId`     | The identifier for the ad unit you want to show.                                                                      |
| `options`      | A collection of [options](#unityadsloadoptions) modifying ad behavior.                                                |
| `showListener` | Optionally shows content with [`IUnityAdsShowListener`](#iunityadsshowlistener) callbacks (versions 3.7.0 and later). |

#### addListener

> **Important:**
>
> Removed in SDK version 4.0. For more information, refer to the [deprecated API classes](/monetization/sdk-integration/android-sdk/api/android-deprecated-apis.md).

```java
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 publishers.

| **Parameter** | **Description**                     |
| ------------- | ----------------------------------- |
| `listener`    | A listener for Unity Ads callbacks. |

#### removeListener

> **Important:**
>
> Removed in SDK version 4.0. For more information, refer to the [deprecated API classes](/monetization/sdk-integration/android-sdk/api/android-deprecated-apis.md).

```java
public static void removeListener(IUnityAdsListener listener)
```

Removes an active \[`IUnityAdsListener`].

| **Parameter** | **Description**                     |
| ------------- | ----------------------------------- |
| `listener`    | A listener for Unity Ads callbacks. |

#### getVersion

```java
public static String getVersion()
```

Returns the current Ads SDK version.

#### getPlacementState

```java
public static PlacementState getPlacementState(String adUnitId)
```

Returns the [state](#placementstate) of a specified ad unit.

| **Parameter** | **Description**                                   |
| ------------- | ------------------------------------------------- |
| `adUnitId`    | The identifier for the ad unit you want to query. |

#### setDebugMode

```java
public static void setDebugMode(boolean debugMode)
```

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

#### getDebugMode

```java
public static boolean getDebugMode()
```

Returns `true` if the SDK is in debug mode.

#### isInitialized

```java
public static boolean isInitialized()
```

Returns `true` if the SDK is initialized successfully, and `false` if it isn't.

#### isSupported

```java
public static bool isSupported()
```

Returns `true` if the SDK is supported on the current platform, and `false` if it isn't.

### UnityAdsLoadOptions

```java
public class UnityAdsLoadOptions extends UnityAdsBaseOptions
```

This class contains optional metadata to include with the [`load`](#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

```java
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##set-ad-markup

```java
public void setObjectId(String objectId)
```

This method sets the loaded ad object ID as the ad object ID to show.

### BannerView

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

| **Parameter** | **Description**                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `activity`    | The current Android [`Activity`](https://developer.android.com/reference/android/app/Activity). |
| `adUnitId`    | The identifier for the ad unit you want to show.                                                |
| `size`        | The [`size`](#unitybannersize) of the banner object.                                            |

#### getPlacementId

```java
public String getPlacementId()
```

Returns the ad unit ID for the Banner ad unit.

#### getSize

```java
public UnityBannerSize getSize()
```

The [`size`](#unitybannersize) of the banner.

#### setListener

```java
public void setListener(IListener listener)
```

Sets the active listener for the banner.

#### getListener

```java
public IListener getListener()
```

Retrieves the active listener for the banner.

#### load##bannerload

```java
public void load()
```

The basic method for requesting an ad for the banner.

#### destroy

```java
public void destroy()

```

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

### UnityBannerSize

```java
public UnityBannerSize(int width, int height)
```

Use this class to define the height and width of a [banner object](#bannerview).

#### getWidth

```java
public int getWidth()
```

Returns the width in pixels of the [banner object](#bannerview).

#### getHeight

```java
public int getHeight()
```

Returns the height in pixels of the [banner object](#bannerview).

## 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`](#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`](#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`](#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`](#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

```java
...
```

The enumerated reasons for an add to fail.

## Interfaces

### IUnityAdsInitializationListener

```java
void onInitializationComplete();
void onInitializationFailed(UnityAds.UnityAdsInitializationError error, String message);
```

Implement this interface to handle [`initialize`](#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`](#unityadsinitializationerror) that caused initialization to fail. |
| `message` | A message associated with the error.                                                                  |

### IUnityAdsLoadListener

```java
void onUnityAdsAdLoaded(String placementId);
void onUnityAdsFailedToLoad(String placementId, UnityAds.UnityAdsLoadError error, String message);
```

Implement this interface to handle [`load`](#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`](#unityadsloaderror) that caused the load to fail. |
| `message`  | A message associated with the error.                                        |

### IUnityAdsShowListener

```java
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`](#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`](#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`](#unityadsshowcompletionstate) | Indicates whether the ad was skipped or completed.  |

#### onUnityAdsReady

> **Important:**
>
> Removed in SDK version 4.0. For more information, refer to the [deprecated API classes](/monetization/sdk-integration/android-sdk/api/android-deprecated-apis.md).

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

> **Important:**
>
> Removed in SDK version 4.0. For more information, refer to the [deprecated API classes](/monetization/sdk-integration/android-sdk/api/android-deprecated-apis.md).

Specify logic for ad content failing to display due to an error.

| Parameter                 | Description                           |
| ------------------------- | ------------------------------------- |
| [`error`](#unityadserror) | The error that caused the ad to fail. |
| `message`                 | A message associated with the error.  |

#### onUnityAdsDidStart

> **Important:**
>
> Removed in SDK version 4.0. For more information, refer to the [deprecated API classes](/monetization/sdk-integration/android-sdk/api/android-deprecated-apis.md).

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

> **Important:**
>
> Removed in SDK version 4.0. For more information, refer to the [deprecated API classes](/monetization/sdk-integration/android-sdk/api/android-deprecated-apis.md).

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](#finishstate) of the ad showing. |

### IListener

```java
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](#bannerview) that loaded. |

#### onBannerClick

This callback fires when the banner is clicked.

| Parameter      | Description                                   |
| -------------- | --------------------------------------------- |
| `bannerAdView` | The [banner object](#bannerview) that loaded. |

#### onBannerError

This callback fires when an error occurs showing the banner.

| Parameter      | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `bannerAdView` | The [banner object](#bannerview) 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](#bannerview) that loaded. |