# Unity Ads SDK API 参考

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

使用 `Advertisements` 命名空间可以实现基本广告内容，例如奖励或非奖励视频广告、插页式广告或横幅广告。

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

本文包含以下 API 文档：

**类**

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

**枚举**

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

**接口**

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

## 类##classes

### Advertisement##advertisement

#### Initialize##initialize

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

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

| 参数                       | 描述                                                                                                          |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `gameId`                 | 开发者后台中项目的特定于平台的
Unity Game ID（Unity 游戏 ID）。                                                             |
| `testMode`               | 使用测试模式可以在不投放真实广告的情况下测试集成情况。使用
`true` 在测试模式下进行初始化。                                                       |
| `initializationListener` | （可选）使用
[`IUnityAdsInitializationListener`](#iunityadsinitializationlistener)
回调启用 SDK（3.7.0 和更高版本）。 |

#### Load##load

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

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

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

#### IsReady##isready

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

如果指定的广告单元已准备好展示广告，返回 `true`。如果在启用 `enablePerPlacementLoad` 的情况下初始化了 SDK，则必须在调用 [`Show`](#show) 之前先调用 [`Load`](#load)。

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

#### Show##show

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

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

| **参数**         | **描述**                                                                                   |
| -------------- | ---------------------------------------------------------------------------------------- |
| `adUnitId`     | 要展示的广告单元的标识符。                                                                            |
| `showOptions`  | 一组用于修改广告展示行为的选项（包括 [`resultCallback`](#resultcallback)
）。                            |
| `showListener` | （可选）使用
[`IUnityAdsShowListener`](#iunityadsshowlistener) 回调展示广告内容
（3.7.0 和更高版本）。 |

> **Note:**
>
> 如果在未指定广告单元 ID 的情况下调用 
>
> `Show`
>
> ，则该方法会展示 Unity 标准广告位中加载的内容。在 SDK 4.0 及更高版本中，必须指定广告单元 ID。

#### AddListener##addlistener

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

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

| **参数**     | **描述**                                     |
| ---------- | ------------------------------------------ |
| `listener` | 用于 Unity Ads 回调的[监听器](#iunityadslistener)。 |

#### RemoveListener##removelistener

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

移除活动 [`IUnityAdsListener`](#iunityadslistener)。

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

#### GetPlacementState##getplacementstate

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

```cs
public static PlacementState GetPlacementState(string adUnitId)
```

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

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

#### isInitialized##isinitialized

```cs
public static bool isInitialized
```

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

#### isSupported##issupported

```cs
public static bool isSupported
```

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

#### debugMode##debugmode

```cs
public static bool debugMode
```

如果 SDK 处于调试模式，返回 `true`，否则返回 `false`。调试模式控制 SDK 输出的日志记录级别。

#### version##version

```cs
public static string version
```

返回当前 SDK 版本。

#### isShowing##isshowing

```cs
public static bool isShowing
```

如果当前正在展示广告，返回 `true`，否则返回 `false`。

### 横幅广告##banner

使用此类可[实现横幅广告](/grow/ads/unity-sdk/banner-ads.md)。

#### Load##banner-load

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

加载指定横幅广告单元的广告内容。如果在启用 `enablePerPlacementLoad` 的情况下初始化了 SDK，则必须在调用 [`Show`](#banner-show) 之前先调用 `Load`。

| **参数**     | **描述**                                                  |
| ---------- | ------------------------------------------------------- |
| `adUnitId` | 要加载的横幅广告单元的标识符。                                         |
| `options`  | 一组用于在加载横幅广告时
向 SDK 通知相关事件的[选项](#bannerloadoptions)。 |

#### Show##banner-show

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

展示指定横幅广告单元的广告内容。必须在调用 `Show` 之前先调用 [`Load`](#banner-load)。

| **参数**     | **描述**                                         |
| ---------- | ---------------------------------------------- |
| `adUnitId` | 要加载的横幅广告单元的标识符。                                |
| `options`  | 一组用于在展示横幅广告时向 SDK 通知相关事件的[选项](#banneroptions)。 |

#### Hide##banner-hide

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

允许隐藏横幅广告，而不完全将其销毁。

#### SetPosition##setposition

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

设置横幅广告在设备上的位置。

| **参数**           | **描述**                          |
| ---------------- | ------------------------------- |
| `bannerPosition` | 用作横幅广告锚点的[位置](#bannerposition)。 |

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

```cs
public static bool isLoaded
```

如果当前加载了要展示的横幅广告，返回 `true`，否则返回 `false`。

### ShowOptions##showoptions

实现这些选项可以在广告单元中展示内容时向 SDK 通知相关事件。当广告结束时，使用 `ShowOptions.resultCallback` 将 [`ShowResult`](#showresult) 枚举返回给 Show。

#### resultCallback##resultcallback

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

此回调接收广告的结果。

> **Important:**
>
>  
>
> **废弃**
>
> ：改而实现 
>
> [`IUnityAdsListener`](#iunityadslistener)
>
>  并调用 
>
> `Advertisement.AddListener`
>
> 。

#### gamerSid##gamersid

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

为游戏中的特定用户指定标识符。

### BannerLoadOptions##bannerloadoptions

实现这些选项可以在加载横幅广告时向 SDK 通知相关事件。

#### loadCallback##loadcallback

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

横幅广告单元成功加载已准备好展示的内容时触发此回调。

#### errorCallback##errorcallback

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

横幅广告单元加载内容失败时触发此回调。

### BannerOptions##banneroptions

实现这些选项可以在展示横幅广告时向 SDK 通知相关事件。

#### bannerCallback##bannercallback

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

横幅广告对用户可见时触发此回调。

#### hideCallback##hidecallback

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

横幅广告对用户不可见时触发此回调。

#### clickCallback##clickcallback

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

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

## 枚举##enums

### PlacementState##placementstate

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

广告单元的状态枚举。

| **值**          | **描述**        |
| -------------- | ------------- |
| `Ready`        | 广告单元已准备好展示广告。 |
| `NotAvailable` | 广告单元不可用。      |
| `Disabled`     | 已禁用广告单元。      |
| `Waiting`      | 广告单元正在等待准备就绪。 |
| `NoFill`       | 广告单元没有可展示的广告。 |

### ShowResult##showresult

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

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

### UnityAdsInitializationError##unityadsinitializationerror

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

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

### UnityAdsLoadError##unityadsloaderror

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

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

### UnityAdsShowCompletionState##unityadsshowcompletionstate

广告已结束的原因枚举。

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

### UnityAdsShowError##unityadsshowerror

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

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

### BannerPosition##bannerposition

在设备显示屏上锚定横幅广告的位置枚举。

| **值**           | **描述**             |
| --------------- | ------------------ |
| `TOP_LEFT`      | 将横幅广告锚定在屏幕的左上角。    |
| `TOP_CENTER`    | 将横幅广告锚定在屏幕的顶部中央位置。 |
| `TOP_RIGHT`     | 将横幅广告锚定在屏幕的右上角。    |
| `BOTTOM_LEFT`   | 将横幅广告锚定在屏幕的左下角。    |
| `BOTTOM_CENTER` | 将横幅广告锚定在屏幕的底部中央位置。 |
| `BOTTOM_RIGHT`  | 将横幅广告锚定在屏幕的右下角。    |
| `CENTER`        | 将横幅广告锚定在屏幕的中央位置。   |

## 接口##interfaces

### IUnityAdsInitializationListener##iunityadsinitializationlistener

```cs
public interface IUnityAdsInitializationListener {
  void OnInitializationComplete();
  void OnInitializationFailed(UnityAdsInitializationError error, string message);
}
```

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

#### OnInitializationComplete##oninitializationcomplete

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

#### OnInitializationFailed##oninitializationfailed

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

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

### IUnityAdsLoadListener##iunityadsloadlistener

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

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

#### OnUnityAdsLoaded##onunityadsloaded

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

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

#### OnUnityAdsFailedToLoad##onunityadsfailedtoload

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

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

### IUnityAdsShowListener##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);
}
```

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

#### OnUnityAdsShowFailure##onunityadsshowfailure

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

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

#### OnUnityAdsShowStart##onunityadsshowstart

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

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

#### OnUnityAdsShowClick##onunityadsshowclick

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

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

#### OnUnityAdsShowComplete##onunityadsshowcomplete

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

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

### IUnityAdsListener##iunityadslistener

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

实现此接口可以处理各种广告状态。在脚本中实现此监听器可以定义[奖励广告](/grow/ads/unity-sdk/rewarded-ads.md)的逻辑。

#### OnUnityAdsReady##onunityadsready

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

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

#### OnUnityAdsDidError##onunityadsdiderror

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

| **参数**    | **描述**    |
| --------- | --------- |
| `message` | 与错误相关的消息。 |

#### OnUnityAdsDidStart##onunityadsdidstart

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

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

#### OnUnityAdsDidFinish##onunityadsdidfinish

> **Important:**
>
> 已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅
>
> [已弃用的 API 类](/grow/ads/references/deprecated-api-classes.md)
>
> 。

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

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