# Unity Ads SDK API reference

> Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in C# to integrate and control ad behavior in your Unity project.

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

```cs
using UnityEngine.Advertisements;
```

This article contains the following API documentation:

**Classes**

* [`Advertisement`](#advertisement)
* [`Banner`](#banner)
* [`BannerLoadOptions`](#bannerloadoptions)
* [`BannerOptions`](#banneroptions)
* [`ShowOptions`](#showoptions)

**Enums**

* [`ShowResult`](#showresult)
* [`UnityAdsInitializationError`](#unityadsinitializationerror)
* [`UnityAdsLoadError`](#unityadsloaderror)
* [`UnityAdsShowError`](#unityadsshowerror)
* [`UnityAdsShowCompletionState`](#unityadsshowcompletionstate)
* [`BannerPosition`](#bannerposition)

**Interfaces**

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

## Classes##classes

### Advertisement

#### Initialize

```cs
public static void Initialize(string gameId, bool testMode, IUnityAdsInitializationListener initializationListener)
```

Initializes the ads service, with a specified Game ID, [test mode](/monetization/sdk-integration/unity-sdk/test-integration.md) status, and placement load setting.

| Parameter                | Description                                                                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gameId`                 | The platform-specific Unity game identifier for your project, found on
the developer dashboard.                                                 |
| `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

```cs
public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)
```

Loads ad content for a specified ad unit.

| **Parameter**  | **Description**                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `adUnitId`     | The identifier for the ad unit you want to load with ad content.                                                                 |
| `loadListener` | Optionally loads ad content with
[`IUnityAdsLoadListener`](#iunityadsloadlistener) callbacks (versions
3.7.0 and later). |

#### IsReady

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

```cs
static bool IsReady (string adUnitId)
```

Returns `true` if an ad is ready to show in the specified ad unit. If you initialized the SDK with `enablePerPlacementLoad` enabled, you must call [`Load`](#load) before calling [`Show`](#show).

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

#### Show

```cs
public static void Show(string adUnitId, ShowOptions showOptions, IUnityAdsShowListener showListener)
```

Displays loaded ad content in a specified ad unit.

| **Parameter**  | **Description**                                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `adUnitId`     | The identifier for the ad unit you want to show.                                                                              |
| `showOptions`  | A collection of options, including [`resultCallback`](#resultcallback),
for modifying ad behavior.                        |
| `showListener` | Optionally shows content with
[`IUnityAdsShowListener`](#iunityadsshowlistener) callbacks (versions
3.7.0 and later). |

> **Note:**
>
> If you call `Show` without specifying an ad unit ID, the method shows loaded content in the Unity Standard Placement. In SDK versions 4.0 and higher, you must specify an ad unit ID.

#### AddListener

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

```cs
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 mediated publishers.

| **Parameter** | **Description**                                           |
| ------------- | --------------------------------------------------------- |
| `listener`    | A [listener](#iunityadslistener) for Unity Ads callbacks. |

#### RemoveListener

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

```cs
public static void RemoveListener(IUnityAdsListener listener)
```

Removes an active [`IUnityAdsListener`](#iunityadslistener).

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

#### GetPlacementState

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

```cs
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 |

#### isInitialized

```cs
public static bool isInitialized
```

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

#### isSupported

```cs
public static bool isSupported
```

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

#### debugMode

```cs
public static bool debugMode
```

Returns `true` if the SDK is in debug mode, and `false` if it isn't. Debug mode controls the level of logging from the SDK.

#### version

```cs
public static string version
```

Returns the current SDK version.

#### isShowing

```cs
public static bool isShowing
```

Returns `true` if an ad is currently showing, and `false` if it isn't.

### Banner

Use this class to [implement banner ads](/monetization/sdk-integration/unity-sdk/banner-ads.md).

#### Load##banner-load

```cs
public static void Load(string adUnitId, BannerLoadOptions options)
```

Loads ad content for a specified Banner ad unit. If you initialized the SDK with `enablePerPlacementLoad` enabled, you must call `Load` before calling [`Show`](#banner-show).

| **Parameter** | **Description**                                                                                          |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `adUnitId`    | The identifier for the Banner ad unit you want to load.                                                  |
| `options`     | A collection of [options](#bannerloadoptions) that notify the SDK of
events when loading the banner. |

#### Show##banner-show

```cs
public static void Show(string adUnitId, BannerOptions options)
```

Shows ad content for a specified Banner ad unit. You must call [`Load`](#banner-load) before calling `Show`.

| **Parameter** | **Description**                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `adUnitId`    | The identifier for the Banner ad unit you want to load.                                             |
| `options`     | A collection of [options](#banneroptions) that notify the SDK of events when displaying the banner. |

#### Hide##banner-hide

```cs
public static void Hide(bool destroy = false)
```

Allows you to hide a banner ad without destroying it altogether.

#### SetPosition

```cs
public void SetPosition (BannerPosition bannerPosition)
```

Sets the position of the banner ad on the device.

| **Parameter**    | **Description**                                                         |
| ---------------- | ----------------------------------------------------------------------- |
| `bannerPosition` | The [position](#bannerposition) to use as an anchor for your banner ad. |

#### isLoaded##banner-is-loaded

```cs
public static bool isLoaded
```

Returns `true` if a banner ad is currently loaded to show, and `false` if it isn't.

### ShowOptions

Implement these options to notify the SDK of events when showing content in an ad unit. Use `ShowOptions.resultCallback` to pass a [`ShowResult`](#showresult) enum back to Show when the ad finishes.

#### resultCallback

```cs
public ShowResult resultCallback { get; set; }
```

This callback receives the result of an ad.

> **Important:**
>
> **Obsolete**: Implement [`IUnityAdsListener`](#iunityadslistener) and call `Advertisement.AddListener` instead.

#### gamerSid

```cs
public string gamerSid { get; set; }
```

Specify an identifier for a specific user in the game.

### BannerLoadOptions

Implement these options to notify the SDK of events when loading a banner ad.

#### loadCallback

```cs
public LoadCallback loadCallback { get; set; }
```

This callback fires when the Banner ad unit successfully loads content that is ready to show.

#### errorCallback

```cs
public ErrorCallback errorCallback { get; set; }
```

This callback fires when the Banner ad unit failed to load content.

### BannerOptions

Implement these options to notify the SDK of events when displaying a banner ad.

#### bannerCallback

```cs
public BannerCallback bannerCallback { get; set; }
```

This callback fires when the banner is visible to the user.

#### hideCallback

```cs
public BannerCallback hideCallback { get; set; }
```

This callback fires when the banner is hidden from the user.

#### clickCallback

```cs
public BannerCallback clickCallback { get; set; }
```

This callback fires when the user clicks the banner.

## Enums

### PlacementState

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

The enumerated states of an ad unit.

| **Value**      | **Description**                     |
| -------------- | ----------------------------------- |
| `Ready`        | The ad unit is ready to show ads.   |
| `NotAvailable` | The ad unit is not available.       |
| `Disabled`     | The ad unit has been disabled.      |
| `Waiting`      | The ad unit is waiting to be ready. |
| `NoFill`       | The ad unit has no ads to show.     |

### ShowResult

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**                                                        |
| ---------- | ---------------------------------------------------------------------- |
| `Failed`   | Indicates that the ad failed to complete due to a Unity service error. |
| `Skipped`  | Indicates that the user skipped the ad.                                |
| `Finished` | Indicates that the user successfully finished watching the ad.         |

### UnityAdsInitializationError

The enumerated reasons for SDK initialization to fail.

| **Value**             | **Description**                                                                       |
| --------------------- | ------------------------------------------------------------------------------------- |
| `UNKNOWN`             | An error occurred for unknown reasons.                                                |
| `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.                                         |

### 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.                             |
| `UNKNOWN`           | The ad failed to load for an unknown reason.                                      |

### 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. |
| `UNKNOWN`   | The cause of the ad finishing is unknown.                                                                                      |

### UnityAdsShowError

The enumerated reasons for an ad 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.                 |
| `UNKNOWN`            | The ad failed to show for an unknown reason.                                      |

### BannerPosition

The enumerated positions to anchor a banner on the device display.

| **Value**       | **Description**                                       |
| --------------- | ----------------------------------------------------- |
| `TOP_LEFT`      | Anchor the banner to the top-left of the screen.      |
| `TOP_CENTER`    | Anchor the banner to the top-center of the screen.    |
| `TOP_RIGHT`     | Anchor the banner to the top-right of the screen.     |
| `BOTTOM_LEFT`   | Anchor the banner to the bottom-left of the screen.   |
| `BOTTOM_CENTER` | Anchor the banner to the bottom-center of the screen. |
| `BOTTOM_RIGHT`  | Anchor the banner to the bottom-right of the screen.  |
| `CENTER`        | Anchor the banner to the center of the screen.        |

## Interfaces

### IUnityAdsInitializationListener

```cs
public interface IUnityAdsInitializationListener {
  void OnInitializationComplete();
  void OnInitializationFailed(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

```cs
public interface IUnityAdsLoadListener {
  void OnUnityAdsAdLoaded(string adUnitId);
  void OnUnityAdsFailedToLoad(string adUnitId, UnityAdsLoadError error, string message);
}
```

Implement this interface to handle [`Load`](#load) results.

#### OnUnityAdsLoaded

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

### IUnityAdsShowListener

```cs
public interface IUnityAdsShowListener {
  void OnUnityAdsShowFailure(string adUnitId, UnityAdsShowError error, string message);
  void OnUnityAdsShowStart(string adUnitId);
  void OnUnityAdsShowClick(string adUnitId);
  void OnUnityAdsShowComplete(string adUnitId, UnityAdsShowCompletionState showCompletionState);
}
```

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

### IUnityAdsListener

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

```cs
public interface IUnityAdsListener{
  void OnUnityAdsReady(string adUnitId);
  void OnUnityAdsDidError(string message);
  void OnUnityAdsDidStart(string adUnitId);
  void OnUnityAdsDidFinish(string adUnitId, ShowResult showResult);
}
```

Implement this interface to handle various states of an ad. Implement this listener in your script to define logic for [rewarded ads](/monetization/sdk-integration/unity-sdk/rewarded-ads.md).

#### OnUnityAdsReady

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

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

| **Parameter** | **Description**                      |
| ------------- | ------------------------------------ |
| `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/unity-sdk/api/unity-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 content. |

#### OnUnityAdsDidFinish

> **Important:**
>
> Removed in SDK version 4.0. For more information, refer to the [deprecated API classes](/monetization/sdk-integration/unity-sdk/api/unity-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.      |
| `showResult`  | The [resulting user event](#showresult) of the ad showing. |