# Unity Ads Android SDK API 参考

> 通过访问 Unity Ads SDK 公共 API 参考，可以查看在 Java 中可用于集成和控制 Android 应用程序广告行为的类、方法和属性。

本文包含以下 API 文档：

**类**

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

**枚举**

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

**接口**

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

## 类##classes

### UnityAds##unityads

使用此命名空间可以[实现插页式广告内容](/grow/ads/android-sdk/interstitial-ads.md)，例如奖励或非奖励视频广告或横幅广告。

#### initialize##initialize

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

使用指定的 [Game ID（游戏 ID）](/grow/dashboard/get-started/project/settings.md#game-ids)、[测试模式](/grow/ads/optimization/test-ads-integration.md)状态和初始化监听器来初始化广告服务。

| 参数                       | 描述                                                                                                  |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `context`                | 当前 Android [`Context`](https://developer.android.com/reference/android/content/Context)。            |
| `gameId`                 | [Unity Monetization（变现）后台](https://cloud.unity.com/monetization)中项目的特定于平台的 Unity 游戏标识符。             |
| `testMode`               | 使用测试模式可以在不投放真实广告的情况下测试集成情况。使用 `true` 在测试模式下进行初始化。                                                   |
| `initializationListener` | （可选）使用 [`IUnityAdsInitializationListener`](#iunityadsinitializationlistener) 回调启用 SDK（3.7.0 和更高版本）。 |

#### load##load

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

加载指定广告单元的广告内容。必须在调用 [`show`](#show) 之前先调用 `load`。

| **参数**        | **描述**                                                                          |
| ------------- | ------------------------------------------------------------------------------- |
| `adUnitId`    | 要加载广告内容的广告单元的标识符。                                                               |
| `loadOptions` | 一组用于修改广告行为的选项。                                                                  |
| `listener`    | （可选）使用 [`IUnityAdsLoadListener`](#iunityadsloadlistener) 回调加载广告内容（3.7.0 和更高版本）。 |

#### show##show

```java
public static void show(final Activity activity, final String adUnitId, final UnityAdsShowOptions options, final IUnityAdsShowListener showListener)
```

显示指定广告单元中加载的广告内容。

| 参数             | 描述                                                                                     |
| -------------- | -------------------------------------------------------------------------------------- |
| `activity`     | 当前 Android [`Activity`](https://developer.android.com/reference/android/app/Activity)。 |
| `adUnitId`     | 要展示的广告单元的标识符。                                                                          |
| `options`      | 一组用于修改广告行为的[选项](#unityadsloadoptions)。                                                 |
| `showListener` | （可选）使用 [`IUnityAdsShowListener`](#iunityadsshowlistener) 回调展示广告内容（3.7.0 和更高版本）。        |

#### addListener##addlistener

> **Important:**
>
> 已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

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

添加一个用于接收 Unity Ads 回调的监听器。在 3.1.0 及更高版本中，您可以注册多个监听器。这对于[聚合](/grow/ads/mediation/unity-ads-in-mediation.md)客户特别有用。

| **参数**     | **描述**               |
| ---------- | -------------------- |
| `listener` | 用于 Unity Ads 回调的监听器。 |

#### removeListener##removelistener

> **Important:**
>
> 已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

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

移除活动 `IUnityAdsListener`。

| **参数**     | **描述**               |
| ---------- | -------------------- |
| `listener` | 用于 Unity Ads 回调的监听器。 |

#### getVersion##getversion

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

返回当前 Ads SDK 版本。

#### getPlacementState##getplacementstate

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

返回指定广告单元的[状态](#placementstate)。

| **参数**     | **描述**        |
| ---------- | ------------- |
| `adUnitId` | 要查询的广告单元的标识符。 |

#### setDebugMode##setdebugmode

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

控制 SDK 的日志输出量。设置为 `true` 可获得更详细完整的日志记录。

#### getDebugMode##getdebugmode

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

如果 SDK 处于调试模式，返回 `true`。

#### isInitialized##isinitialized

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

如果 SDK 已成功初始化，返回 `true`，否则返回 `false`。

#### isSupported##issupported

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

如果 SDK 在当前平台上受支持，返回 `true`，否则返回 `false`。

### UnityAdsLoadOptions##unityadsloadoptions

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

此类包含要使用 [`load`](#load) 方法添加的可选元数据。在第三方聚合中使用头部竞价的客户应在 Unity Ads 平台中的出价人赢得广告拍卖的情况下使用此类。

#### setAdMarkup##setadmarkup

```java
public void setAdMarkup(String adMarkup)
```

此方法采用从出价人服务返回的广告标记。当 Unity Ads 平台中的出价人赢得头部竞价拍卖时，Unity Ads SDK 会从聚合交易平台接收广告标记。广告标记字符串包含 Unity 加载和展示广告所需的信息。

#### setObjectId##set-ad-markup

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

此方法将加载的广告对象 ID 设置为要展示的广告对象 ID。

### BannerView##bannerview

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

| **参数**     | **描述**                                                                                 |
| ---------- | -------------------------------------------------------------------------------------- |
| `activity` | 当前 Android [`Activity`](https://developer.android.com/reference/android/app/Activity)。 |
| `adUnitId` | 要展示的广告单元的标识符。                                                                          |
| `size`     | 横幅对象的 [`size`](#unitybannersize)。                                                      |

#### getPlacementId##getplacementid

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

返回横幅广告单元的广告单元 ID。

#### getSize##getsize

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

横幅的 [`size`](#unitybannersize)。

#### setListener##setlistener

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

设置横幅广告的活动监听器。

#### getListener##getlistener

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

获取横幅广告的活动监听器。

#### load##bannerload

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

用于请求横幅广告的基本方法。

#### destroy##destroy

```java
public void destroy()

```

不再使用横幅时，调用此方法可将其从 View 层级视图中移除。

### UnityBannerSize##unitybannersize

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

使用此类可以定义[横幅对象](#bannerview)的高度和宽度。

#### getWidth##getwidth

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

返回[横幅对象](#bannerview)的宽度（以像素为单位）。

#### getHeight##getheight

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

返回[横幅对象](#bannerview)的高度（以像素为单位）。

## 枚举##enums

### PlacementState##placementstate

广告单元的状态枚举。

| 值               | 描述            |
| --------------- | ------------- |
| `READY`         | 广告单元已准备好展示广告。 |
| `NOT_AVAILABLE` | 广告单元不可用。      |
| `DISABLED`      | 已禁用广告单元。      |
| `WAITING`       | 广告单元正在等待准备就绪。 |
| `NO_FILL`       | 广告单元没有要展示的广告。 |

### FinishState##finishstate

用户与广告互动的状态枚举。广告播放完成时，SDK 会将此值传递给 [`onUnityAdsDidFinish`](#onunityadsdidfinish) 回调方法。

| 值           | 描述                       |
| ----------- | ------------------------ |
| `ERROR`     | 表示由于 Unity 服务错误而未能播放完广告。 |
| `SKIPPED`   | 表示用户跳过了广告。               |
| `COMPLETED` | 表示用户已成功看完广告。             |

### UnityAdsInitializationError##unityadsinitializationerror

SDK 初始化失败的原因枚举。

| 值                     | 描述                                            |
| --------------------- | --------------------------------------------- |
| `INTERNAL_ERROR`      | 由于环境或内部服务而发生错误。                               |
| `INVALID_ARGUMENT`    | 由于 [`initialize`](#initialize) 方法中的参数无效而发生错误。 |
| `AD_BLOCKER_DETECTED` | 由于 URL 被阻止而发生错误。                              |

### UnityAdsShowCompletionState##unityadsshowcompletionstate

广告已结束的原因枚举。

| 值           | 描述                                |
| ----------- | --------------------------------- |
| `SKIPPED`   | 表示用户跳过了广告。                        |
| `COMPLETED` | 表示广告已完整播放。这通常表明用户可以因观看完整的广告而获得奖励。 |

### UnityAdsLoadError##unityadsloaderror

广告单元加载失败的原因枚举。

| **值**               | **描述**                                |
| ------------------- | ------------------------------------- |
| `INITIALIZE_FAILED` | 由于 SDK 未初始化而导致广告加载失败。                 |
| `INTERNAL_ERROR`    | 由于内部 Unity Ads 服务错误而导致广告加载失败。         |
| `INVALID_ARGUMENT`  | 由于 [`load`](#load) 方法中的参数无效而导致广告加载失败。 |
| `NO_FILL`           | 由于广告平台上没有可用的内容而导致广告加载失败。              |
| `TIMEOUT`           | 广告未能在指定的时间范围内加载。                      |

### UnityAdsShowError##unityadsshowerror

广告单元展示失败的原因枚举。

| 值                    | 描述                                    |
| -------------------- | ------------------------------------- |
| `NOT_INITIALIZED`    | 由于 SDK 未初始化而导致广告展示失败。                 |
| `NOT_READY`          | 由于广告单元尚未准备就绪而导致广告展示失败。                |
| `VIDEO_PLAYER_ERROR` | 由于媒体播放器错误而导致广告展示失败。                   |
| `INVALID_ARGUMENT`   | 由于 [`show`](#show) 方法中的参数无效而导致广告展示失败。 |
| `NO_CONNECTION`      | 由于互联网连接错误而导致广告展示失败。                   |
| `ALREADY_SHOWING`    | 由于广告已在展示而导致广告展示失败。                    |
| `INTERNAL_ERROR`     | 由于内部 Unity Ads 服务错误而导致广告展示失败。         |

### UnityAdsError##unityadserror

```java
...
```

广告失败的原因枚举。

## 接口##interfaces

### IUnityAdsInitializationListener##iunityadsinitializationlistener

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

实现此接口可以处理 [`initialize`](#initialize) 结果。

#### onInitializationComplete##oninitializationcomplete

此回调方法处理 SDK 成功初始化的逻辑。

#### onInitializationFailed##oninitializationfailed

此回调方法处理 SDK 初始化失败的逻辑。

| 参数        | 描述                                                                      |
| --------- | ----------------------------------------------------------------------- |
| `error`   | 导致初始化失败的 [`UnityAdsInitializationError`](#unityadsinitializationerror)。 |
| `message` | 与错误相关的消息。                                                               |

### IUnityAdsLoadListener##iunityadsloadlistener

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

实现此接口可以处理 [`load`](#load) 结果。

#### onUnityAdsAdLoaded##onunityadsadloaded

此回调方法处理广告单元成功加载的逻辑。

| 参数         | 描述              |
| ---------- | --------------- |
| `adUnitId` | 已加载内容的广告单元的标识符。 |

#### onUnityAdsFailedToLoad##onunityadsfailedtoload

此回调方法处理广告单元加载失败的逻辑。

| 参数         | 描述                                                 |
| ---------- | -------------------------------------------------- |
| `adUnitId` | 内容加载失败的广告单元的标识符。                                   |
| `error`    | 导致加载失败的 [`UnityAdsLoadError`](#unityadsloaderror)。 |
| `message`  | 与错误相关的消息。                                          |

### IUnityAdsShowListener##iunityadsshowlistener

```java
void onUnityAdsShowFailure(String placementId, UnityAds.UnityAdsShowError error, String message);
void onUnityAdsShowStart(String placementId);
void onUnityAdsShowClick(String placementId);
UnityAds.UnityAdsShowCompletionState state;
```

实现此接口可以处理 [`show`](#show) 结果。

#### onUnityAdsShowFailure##onunityadsshowfailure

此回调方法处理广告单元展示失败的逻辑。

| 参数         | 描述                                                 |
| ---------- | -------------------------------------------------- |
| `adUnitId` | 展示内容失败的广告单元的标识符。                                   |
| `error`    | 导致展示失败的 [`UnityAdsShowError`](#unityadsshowerror)。 |
| `message`  | 与错误相关的消息。                                          |

#### onUnityAdsShowStart##onunityadsshowstart

此回调方法处理广告开始播放的逻辑。

| 参数         | 描述             |
| ---------- | -------------- |
| `adUnitId` | 展示内容的广告单元的标识符。 |

#### onUnityAdsShowClick##onunityadsshowclick

此回调方法处理用户点击广告的逻辑。

| 参数         | 描述             |
| ---------- | -------------- |
| `adUnitId` | 展示内容的广告单元的标识符。 |

#### onUnityAdsShowComplete##onunityadsshowcomplete

此回调方法处理广告完成的逻辑。

| 参数                                                    | 描述             |
| ----------------------------------------------------- | -------------- |
| `adUnitId`                                            | 展示内容的广告单元的标识符。 |
| [`showCompletionState`](#unityadsshowcompletionstate) | 表示广告已跳过或完成。    |

#### onUnityAdsReady##onunityadsready

> **Important:**
>
> 已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

指定已准备好通过指定广告单元展示的广告内容的逻辑。

| 参数         | 描述              |
| ---------- | --------------- |
| `adUnitId` | 已准备就绪的广告单元的标识符。 |

#### onUnityAdsDidError##onunityadsdiderror

> **Important:**
>
> 已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

指定由于错误而导致广告内容展示失败的逻辑。

| 参数                        | 描述         |
| ------------------------- | ---------- |
| [`error`](#unityadserror) | 导致广告失败的错误。 |
| `message`                 | 与错误相关的消息。  |

#### onUnityAdsDidStart##onunityadsdidstart

> **Important:**
>
> 已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

指定玩家触发广告展示的逻辑。

| 参数         | 描述               |
| ---------- | ---------------- |
| `adUnitId` | 正在展示广告的广告单元的标识符。 |

#### OnUnityAdsDidFinish##onunityadsdidfinish

> **Important:**
>
> 已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

指定玩家完整观看广告的逻辑。

| 参数         | 描述                           |
| ---------- | ---------------------------- |
| `adUnitId` | 完成广告展示的广告单元的标识符。             |
| `result`   | 广告展示的[结果用户事件](#finishstate)。 |

### IListener##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##onbannerloaded

横幅完成广告加载时触发此回调。view 参数将引用应插入 View 层级视图中的横幅。

| 参数             | 描述                      |
| -------------- | ----------------------- |
| `bannerAdView` | 加载的[横幅对象](#bannerview)。 |

#### onBannerClick##onbannerclick

点击横幅广告时触发此回调。

| 参数             | 描述                      |
| -------------- | ----------------------- |
| `bannerAdView` | 加载的[横幅对象](#bannerview)。 |

#### onBannerError##onbannererror

在横幅广告展示过程中发生错误时触发此回调。

| 参数             | 描述                      |
| -------------- | ----------------------- |
| `bannerAdView` | 加载的[横幅对象](#bannerview)。 |
| `errorInfo`    | 一个包含横幅广告加载错误相关信息的类。     |

#### onBannerLeftApplication##onbannerleftapplication

横幅广告链接到应用程序外部时触发此回调。

| 参数             | 描述                      |
| -------------- | ----------------------- |
| `bannerAdView` | 加载的[横幅对象](#bannerview)。 |