# Unity Ads Android SDK API 参考 - Kotlin 和 Java

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

在将 Unity Ads 集成到 Android 应用程序时，请使用此 Unity Ads Android SDK API 参考。

在使用此 API 之前，请确保已导入 `UnityAds` 库以在您的应用程序中启用变现功能。有关更多信息，请参阅 [导入 UnityAds 库](/ads-android/4.19.0/sdk-integration/import-library.md)。

## 类##classes

### BannerAd##bannerad

`BannerAd` 类用于管理横幅广告的加载和显示。

### BannerLoadConfiguration##bannerloadconfiguration

封装加载 `BannerAd` 所需的选项。

| **参数**              | **描述**                              | **必需** |
| ------------------- | ----------------------------------- | ------ |
| `placementId`       | 横幅广告位的唯一标识符。                        | 是      |
| `bannerSize`        | 广告的 `BannerSize`（以像素为单位的宽度和高度）。     | 是      |
| `adMarkup`          | 竞价场景的广告标记。                          | 否      |
| `mediationInfo`     | 聚合合作伙伴信息。                           | 否      |
| `mediationAdUnitId` | 由聚合用于跟踪效果。                          | 否      |
| `extras`            | 附加键值参数的映射。                          | 否      |
| `listener`          | 用于处理横幅广告生命周期事件的 BannerShowListener。 | 否      |

1. **Kotlin**

   ```kotlin
   val bannerLoadConfiguration = BannerLoadConfiguration.Builder(\"banner_placement\", bannerSize)
   	.withAdMarkup("ad_markup")
   	.withMediationInfo(mediationInfo)
   	.withMediationAdUnitId("mediation_ad_unit_id")
     .withExtras(mapOf(\"key\" to \"value\"))
     .withListener(bannerListener)
     .build()
   ```

2. **Java**

   ```java
   BannerLoadConfiguration bannerLoadConfiguration = BannerLoadConfiguration.Builder(\"banner_placement\", bannerSize)
   	.withAdMarkup("ad_markup")
   	.withMediationInfo(mediationInfo)
   	.withMediationAdUnitId("mediation_ad_unit_id")
     .withExtras(Collections.singletonMap("key", "value"))
     .withListener(bannerListener)
     .build()
   ```

#### BannerLoadConfiguration.Builder##bannerloadconfiguration.builder

用于创建 `BannerLoadConfiguration` 实例的构建器类。

##### 构造函数##constructor

```kotlin
Builder(placementId:String, bannerSize:BannerSize)
```

| **参数**        | **描述**                          | **必需** |
| ------------- | ------------------------------- | ------ |
| `placementId` | 横幅广告位的唯一标识符。                    | 是      |
| `bannerSize`  | 广告的 `BannerSize`（以像素为单位的宽度和高度）。 | 是      |

**返回**：一个新的 `BannerLoadConfiguration.Builder` 实例。

##### 构建器方法##builder-methods

| **方法**                             | **参数**                                           | **必需** | **返回**                    | **描述**                                      |
| ---------------------------------- | ------------------------------------------------ | ------ | ------------------------- | ------------------------------------------- |
| `withAdMarkup(String)`             | `adMarkup`：竞价场景的广告标记。                            | `No`   | `Builder`                 | 设置广告标记并返回构建器以进行链式调用。                        |
| `withMediationInfo(MediationInfo)` | `mediationInfo`：聚合合作伙伴信息。                        | `No`   | `Builder`                 | 设置聚合信息并返回构建器以进行链式调用。                        |
| `withMediationAdUnitId(String)`    | `mediationAdUnitId`：由聚合用于跟踪效果。                   | `No`   | `Builder`                 | 设置聚合广告单元 ID 并返回构建器以进行链式调用。                  |
| `withExtras(Map<String, String>)`  | `extras`：附加键值参数的映射。多次调用此方法将覆盖之前的值。               | `No`   | `Builder`                 | 设置 extras 映射并返回构建器以进行链式调用。                  |
| `withListener(BannerShowListener)` | `listener`：一个用于处理横幅广告生命周期事件的 BannerShowListener。 | `No`   | `Builder`                 | 设置显示监听器并返回构建器以进行链式调用。                       |
| `build()`                          | None                                             | `No`   | `BannerLoadConfiguration` | 创建并返回带有已配置参数的 `BannerLoadConfiguration` 实例。 |

1. **Kotlin**

   ```kotlin
   val bannerLoadConfiguration = BannerLoadConfiguration.Builder(\"banner_placement\", bannerSize)
       .withAdMarkup("ad_markup")
       .withMediationInfo(mediationInfo)
       .withMediationAdUnitId("mediation_ad_unit_id")
       .withExtras(mapOf(\"key\" to \"value\"))
       .withListener(bannerListener)
       .build()
   ```

2. **Java**

   ```java
   BannerLoadConfiguration bannerLoadConfiguration = new BannerLoadConfiguration.Builder(\"banner_placement\", bannerSize)
       .withAdMarkup("ad_markup")
       .withMediationInfo(mediationInfo)
       .withMediationAdUnitId("mediation_ad_unit_id")
       .withExtras(Collections.singletonMap("key", "value"))
       .withListener(bannerListener)
       .build();
   ```

### load()##load()

使用指定的 BannerLoadConfiguration 加载横幅广告。

| **参数**          | **描述**                                                 | **必需** |
| --------------- | ------------------------------------------------------ | ------ |
| `configuration` | 包含横幅特定加载选项的 `BannerLoadConfiguration` 实例。              | 是      |
| `listener`      | 一个 `BannerLoadListener`，在加载完成时被调用，提供 `BannerAd` 实例或错误。 | 是      |

**返回**：`Unit` (void) - 这是一个异步方法，会立即返回。结果通过 `BannerLoadListener` 回调提供。

1. **Kotlin**

   ```kotlin
   val bannerSize = BannerSize(320, 50)
   val loadConfig = BannerLoadConfiguration.Builder(\"banner_placement\", bannerSize).build()
   BannerAd.load(loadConfig, { bannerAd, error ->
       if (bannerAd != null) {
           // 横幅加载成功，您现在可以将其添加到视图层级中
           this.bannerAd = bannerAd
       } else {
           // 处理加载错误
       }
   })
   ```

2. **Java**

   ```java
   BannerSize bannerSize = new BannerSize(320, 50);
   BannerLoadConfiguration loadConfig = new BannerLoadConfiguration.Builder(\"banner_placement\", bannerSize).build();
   BannerAd.load(loadConfig, (bannerAd, error) -> {
       if (bannerAd != null) {
           // 横幅加载成功，您现在可以将其添加到视图层级中
           this.bannerAd = bannerAd;
       } else {
           // 处理加载错误
       }
   });
   ```

### view##view

提供对横幅广告实例访问权限的视图属性。使用此属性可将横幅广告插入到您应用现有视图层级中的所需位置。

**返回**：`View?` (可为空的 View) - 包含横幅广告的 Android View，如果广告未成功加载，则返回 null。

1. **Kotlin**

   ```kotlin
   // 假设 'bannerAd' 是已加载的 BannerAd 实例
   // 假设 'adPlaceholder' 是布局中您想要显示广告的 ViewGroup（例如 LinearLayout、FrameLayout）

   bannerAd.view?.let {
       adPlaceholder.addView(it)
   }
   ```

2. **Java**

   ```java
   // 假设 'bannerAd' 是已加载的 BannerAd 实例
   // 假设 'adPlaceholder' 是布局中您想要显示广告的 ViewGroup（例如 LinearLayout、FrameLayout）

   if (bannerAd.getView() != null) {
       adPlaceholder.addView(bannerAd.getView());
   }
   ```

### BannerView##bannerview

> **Warning:**
>
> \*\*弃用版本 4.19.0。**计划在 5.0.0 版本中移除。**
>
> 改用 [`BannerAd`](/ads-android/4.19.0/sdk-integration/api/android-api.md#bannerad)。通过 `ad.getView()` 访问 Android `View`。有关迁移详情，请参阅 [Android 弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`BannerView` 类是之前用于加载和显示横幅广告的 API。

### BannerView\.IListener##bannerview\.ilistener

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在 5.0.0 版本中移除。**
>
> 改用 [`BannerLoadListener`](/ads-android/4.19.0/sdk-integration/api/android-api.md#bannerloadlistener) 和 [`BannerShowListener`](/ads-android/4.19.0/sdk-integration/api/android-api.md#bannershowlistener)。有关迁移详情，请参阅 [Android 已弃用的 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`BannerView.IListener` 是之前用于处理横幅广告生命周期事件的接口。

### BannerSize##bannersize

表示横幅广告尺寸的数据类。

| **参数**   | **描述**           | **必需** |
| -------- | ---------------- | ------ |
| `width`  | 横幅广告的宽度（以像素为单位）。 | 是      |
| `height` | 横幅广告的高度（以像素为单位）。 | 是      |

1. **Kotlin**

   ```kotlin
   val bannerSize = BannerSize(320, 50)
   ```

2. **Java**

   ```java
   BannerSize bannerSize = new BannerSize(320, 50);
   ```

### UnityBannerSize##unitybannersize

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在 5.0.0 版本中移除。**
>
> 改用 [`BannerSize`](/ads-android/4.19.0/sdk-integration/api/android-api.md#bannersize)。请参阅 [Android 已弃用的 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md) 以了解迁移详情。

`UnityBannerSize` 是之前用于横幅广告尺寸的枚举。

## InitializationConfiguration##initializationconfiguration

一个包含 SDK 初始化所有设置的类。此类的实例是使用其 `Builder` 创建的。

| **参数**              | **描述**                                    | **必需** |
| ------------------- | ----------------------------------------- | ------ |
| `gameId`            | 您在 Unity Ads 变现控制面板中的唯一游戏标识符。             | 是      |
| `isTestModeEnabled` | 一个启用测试模式的布尔值。当为 true 时，仅显示测试广告。默认为 false。 | 否      |
| `logLevel`          | 指定日志输出的详细程度。请参阅 `LogLevel`。默认为 INFO。      | 否      |
| `mediationInfo`     | 包含有关聚合合作伙伴的信息的对象。请参阅 `MediationInfo`。     | 否      |
| `extras`            | 用于高级配置的附加键值参数映射。                          | 否      |

### InitializationConfiguration.Builder##initializationconfiguration.builder

用于创建 `InitializationConfiguration` 实例的构建器类。

#### 构造函数##constructor

```kotlin
Builder(gameId：String)
```

| **参数**   | **描述**                        | **必需** |
| -------- | ----------------------------- | ------ |
| `gameId` | 您在 Unity Ads 变现控制面板中的唯一游戏标识符。 | 是      |

**返回**：一个新的 `InitializationConfiguration.Builder` 实例。

#### 构建器方法##builder-methods

| **方法**                             | **参数**                                                        | **必需** | **返回**                        | **描述**                                          |
| ---------------------------------- | ------------------------------------------------------------- | ------ | ----------------------------- | ----------------------------------------------- |
| `withTestMode(Boolean)`            | `isTestModeEnabled`：一个启用测试模式的布尔值。当为 true 时，仅显示测试广告。默认为 false。 | `No`   | `Builder`                     | 设置测试模式并返回构建器以进行链式调用。                            |
| `withLogLevel(LogLevel)`           | `logLevel`：指定日志输出的详细程度。请参阅 `LogLevel`。默认为 INFO。               | `No`   | `Builder`                     | 设置日志级别并返回构建器以进行链式调用。                            |
| `withMediationInfo(MediationInfo)` | `mediationInfo`：一个包含有关聚合合作伙伴信息的对象。                            | `No`   | `Builder`                     | 设置聚合信息并返回构建器以进行链式调用。                            |
| `withExtras(Map<String, String>)`  | `extras`：一个包含高级配置的附加键值参数映射。                                   | `No`   | `Builder`                     | 设置附加参数映射并返回构建器以进行链式调用。                          |
| `build()`                          | None                                                          | `No`   | `InitializationConfiguration` | 创建并返回带有已配置参数的 `InitializationConfiguration` 实例。 |

1. **Kotlin**

   ```kotlin
   val config = InitializationConfiguration.Builder(\"YOUR_GAME_ID\")
       .withTestMode(true)
       .withLogLevel(LogLevel.DEBUG)
       .withMediationInfo(mediationInfo)
       .withExtras(mapOf(\"key\" to \"value\"))
       .build()
   ```

2. **Java**

   ```java
   InitializationConfiguration config = new InitializationConfiguration.Builder(\"YOUR_GAME_ID\")
       .withTestMode(true)
       .withLogLevel(LogLevel.DEBUG)
       .withMediationInfo(mediationInfo)
       .withExtras(Collections.singletonMap("key", "value"))
       .build();
   ```

### initialize()##initialize()

使用指定的配置初始化 Unity Ads SDK。当初始化成功或失败完成时，将调用 `InitializationListener`。

| **参数**          | **描述**                                                  | **必需** |
| --------------- | ------------------------------------------------------- | ------ |
| `configuration` | 包含初始化 SDK 所需设置的 `InitializationConfiguration` 对象。       | 否      |
| `listener`      | 完成时将调用 `InitializationListener`，指示成功或通过可选的错误消息详细说明失败原因。 | 否      |

**返回**：`Unit` (void) - 这是一个异步方法，会立即返回。结果通过 `InitializationListener` 回调提供。

1. **Kotlin**

   ```kotlin
   @OptIn(UnityAdsExperimental::class)
   fun initializeUnityAds(context:上下文) {
       val config = InitializationConfiguration.Builder(\"YOUR_GAME_ID\")
           .withTestMode(true)
           .build()

       val listener = InitializationListener { error ->
           if (error == null) {
               // Initialization successful
           } else {
               // Handle initialization error
           }
       }
       UnityAds.initialize(config, listener)
   }
   ```

2. **Java**

   ```java
   @OptIn(markerClass = UnityAdsExperimental.class)
   void initializeUnityAds(Context context) {
       InitializationConfiguration config = new InitializationConfiguration.Builder(\"YOUR_GAME_ID\")
           .withTestMode(true)
           .build();

       InitializationListener listener = error -> {
           if (error == null) {
               // Initialization successful
           } else {
               // Handle initialization error
           }
       };
       UnityAds.initialize(config, listener);
   }
   ```

## InterstitialAd##interstitialad

`InterstitialAd` 类管理全屏插页式广告的加载和展示。

### load()##load()

使用指定的 LoadConfiguration 加载插页式广告。

| **参数**          | **描述**                                                                | **必需** |
| --------------- | --------------------------------------------------------------------- | ------ |
| `configuration` | 包含广告加载选项的 `LoadConfiguration` 实例。                                     | 否      |
| `listener`      | 加载完成时调用的 `LoadListener` 回调。如果成功，则返回 `InterstitialAd` 实例；如果加载失败，则返回错误。 | 否      |

1. **Kotlin**

   ```kotlin
   InterstitialAd.load(loadConfig, { interstitialAd, error ->
       if (interstitialAd != null) {
           // 广告加载成功，准备展示
           this.interstitialAd = interstitialAd
       } else {
           // 处理加载错误
       }
   })
   ```

2. **Java**

   ```java
   InterstitialAd.load(loadConfig, (interstitialAd, error) -> {
       if (interstitialAd != null) {
           // 广告加载成功，准备展示
           this.interstitialAd = interstitialAd;
       } else {
           // 处理加载错误
       }
   });
   ```

### show()##show()

显示之前加载的插页式广告。

| **参数**          | **描述**                            | **必需** |
| --------------- | --------------------------------- | ------ |
| `configuration` | 包含广告展示选项的 `ShowConfiguration` 实例。 | 否      |
| `listener`      | 用于处理广告生命周期事件的可选 `ShowListener`。   | 否      |

**返回**：`Unit` (void) - 此方法在启动广告展示流程后立即返回。生命周期事件通过 `ShowListener` 回调提供。

1. **Kotlin**

   ```kotlin
   interstitialAd.show(showConfig, interstitialShowListener)
   ```

2. **Java**

   ```java
   interstitialAd.show(showConfig, interstitialShowListener);
   ```

## LoadConfiguration##loadconfiguration

封装用于加载 `InterstitialAd` 和 `RewardedAd` 格式的选项。

| **参数**              | **描述**                          | **必需** |
| ------------------- | ------------------------------- | ------ |
| `placementId`       | 您的广告位的唯一标识符，可在 Unity 变现控制面板上找到。 | 是      |
| `adMarkup`          | 竞价场景的广告标记。                      | 否      |
| `mediationInfo`     | 聚合合作伙伴信息。                       | 否      |
| `mediationAdUnitId` | 由聚合用于跟踪效果。                      | 否      |
| `extras`            | 附加键值参数的映射。                      | 否      |

1. **Kotlin**

   ```kotlin
   val loadConfiguration = LoadConfiguration.Builder(\"interstitial_placement\")
   	.withAdMarkup("ad_markup")
   	.withMediationInfo(mediationInfo)
   	.withMediationAdUnitId("mediation_ad_unit_id")
     .withExtras(mapOf(\"key\" to \"value\")) 
     // 多次调用此方法将覆盖之前的值。
     .build()
   ```

2. **Java**

   ```java
   LoadConfiguration loadConfiguration = new LoadConfiguration.Builder(\"interstitial_placement\")
   	.withAdMarkup("ad_markup")
   	.withMediationInfo(mediationInfo)
   	.withMediationAdUnitId("mediation_ad_unit_id")
     .withExtras(Collections.singletonMap("key", "value"))
     .build();
   ```

### LoadConfiguration.Builder##loadconfiguration.builder

用于创建 `LoadConfiguration` 实例的构建器类。

#### 构造函数##constructor

```kotlin
Builder(placementId:字符串)
```

| **参数**        | **描述**                          | **必需** |
| ------------- | ------------------------------- | ------ |
| `placementId` | 您的广告位的唯一标识符，可在 Unity 变现控制面板上找到。 | 是      |

**返回**：一个新的 `LoadConfiguration.Builder` 实例。

#### 构建器方法##builder-methods

| **方法**                             | **参数**                             | **必需** | **返回**              | **描述**                              |
| ---------------------------------- | ---------------------------------- | ------ | ------------------- | ----------------------------------- |
| `withAdMarkup(String)`             | `adMarkup`：用于竞价场景的广告标记。            | 否      | `Builder`           | 设置广告标记并返回构建器以进行链式调用。                |
| `withMediationInfo(MediationInfo)` | `mediationInfo`：聚合合作伙伴信息。          | 否      | `Builder`           | 设置聚合信息并返回构建器以进行链式调用。                |
| `withMediationAdUnitId(String)`    | `mediationAdUnitId`：由聚合用于跟踪效果。     | 否      | `Builder`           | 设置聚合广告单元 ID 并返回构建器以进行链式调用。          |
| `withExtras(Map<String, String>)`  | `extras`：其他键值参数的映射。多次调用此方法将覆盖之前的值。 | 否      | `Builder`           | 设置 extras 映射并返回构建器以进行链式调用。          |
| `build()`                          | None                               | 否      | `LoadConfiguration` | 创建并返回配置了参数的 `LoadConfiguration` 实例。 |

### UnityAdsLoadOptions##unityadsloadoptions

> **Warning:**
>
> **已弃用于版本 4.19.0.计划在 5.0.0 版本中移除。**
>
> 改用 [`LoadConfiguration.Builder`](/ads-android/4.19.0/sdk-integration/api/android-api.md#loadconfiguration.builder)。有关迁移详情，请参阅 [Android 弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`UnityAdsLoadOptions` 是之前用于指定广告加载选项的类。

## MediationInfo##mediationinfo

一个包含所用聚合合作伙伴相关信息的类。

| **参数**           | **描述**                   | **必需** |
| ---------------- | ------------------------ | ------ |
| `name`           | 聚合合作伙伴的名称。               | 是      |
| `version`        | 聚合合作伙伴 SDK 的版本。          | 是      |
| `adapterVersion` | 聚合合作伙伴的 Unity Ads 适配器版本。 | 是      |

1. **Kotlin**

   ```kotlin
   val mediationInfo = MediationInfo("partner_name", "1.2.3", "4.5.6")
   ```

2. **Java**

   ```java
   MediationInfo mediationInfo = new MediationInfo("partner_name", "1.2.3", "4.5.6");
   ```

### MediationMetaData##mediationmetadata

> **Warning:**
>
> \*\*已弃用于版本 4.19.0。\*\*计划在 5.0.0 版本中移除。
>
> 改用 [`MediationInfo`](/ads-android/4.19.0/sdk-integration/api/android-api.md#mediationinfo)。有关迁移详情，请参阅 [Android 弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`MediationMetaData` 是之前用于传递聚合合作伙伴信息的类。

## RewardedAd##rewardedad

`RewardedAd` 类用于管理激励视频广告的加载和显示。

### load()##load()

使用指定的 `LoadConfiguration` 加载激励广告。

| **参数**          | **描述**                                           | **必需** |
| --------------- | ------------------------------------------------ | ------ |
| `configuration` | 包含广告加载选项的 `LoadConfiguration` 实例。                | 是      |
| `listener`      | 一个 `LoadListener`，在加载完成时被调用，提供 RewardedAd 实例或错误。 | 是      |

1. **Kotlin**

   ```kotlin
   RewardedAd.load(loadConfig, { rewardedAd, error ->
       if (rewardedAd != null) {
           // 广告加载成功，准备展示
           this.rewardedAd = rewardedAd
       } else {
           // 处理加载错误
       }
   })
   ```

2. **Java**

   ```java
   RewardedAd.load(loadConfig, (rewardedAd, error) -> {
       if (rewardedAd != null) {
           // 广告加载成功，准备展示
           this.rewardedAd = rewardedAd;
       } else {
           // 处理加载错误
       }
   });
   ```

### show()##show()

显示先前加载的激励广告。

| **参数**          | **描述**                                  | **必需** |
| --------------- | --------------------------------------- | ------ |
| `configuration` | 包含广告展示选项的 `ShowConfiguration` 实例。       | 是      |
| `listener`      | 一个可选的 `ShowListener`，用于处理广告事件，包括用户奖励回调。 | 是      |

**返回**：`Unit` (void) - 此方法在启动广告展示流程后立即返回。生命周期事件通过 `ShowListener` 回调提供。

1. **Kotlin**

   ```kotlin
   rewardAd.show(showConfig, rewardedAdShowListener)
   ```

2. **Java**

   ```java
   rewardedAd.show(showConfig, rewardedAdShowListener);
   ```

## ShowConfiguration##showconfiguration

封装用于显示 `InterstitialAd` 和 `RewardedAd` 格式的附加选项。

| **参数**               | **描述**             | **必需** |
| -------------------- | ------------------ | ------ |
| `customRewardString` | 用于跟踪完成情况。          | 否      |
| `extras`             | 在显示广告时传递的附加键值参数映射。 | 否      |

1. **Kotlin**

   ```kotlin
   val showConfiguration = ShowConfiguration.Builder()
   .withCustomRewardString("custom_reward_string")
   .withExtras(mapOf(\"key\" to \"value\"))
   .build()
   ```

2. **Java**

   ```java
   ShowConfiguration showConfiguration = new ShowConfiguration.Builder()
   .withCustomRewardString("custom_reward_string")
   .withExtras(Collections.singletonMap("key", "value"))
   .build();
   ```

### ShowConfiguration.Builder##showconfiguration.builder

用于创建 `ShowConfiguration` 实例的构建器类。

#### 构造函数##constructor

```kotlin
构建器()
```

**返回**：一个新的 `ShowConfiguration.Builder` 实例。

#### 构建器方法##builder-methods

| **方法**                            | **参数**                         | **必需**           | **返回**              | **描述**                                |
| --------------------------------- | ------------------------------ | ---------------- | ------------------- | ------------------------------------- |
| `withCustomRewardString(String)`  | `customRewardString`：用于跟踪完成情况。 | `No`             | `Builder`           | 设置自定义奖励字符串并返回构建器以进行链式调用。              |
| `withExtras(Map<String, String>)` | `extras`：在展示广告时传递的额外键值参数映射。    | `No`             | `Builder`           | 设置额外参数映射并返回构建器以进行链式调用。                |
| `build()`                         | None                           | `Not applicable` | `ShowConfiguration` | 创建并返回带有已配置参数的 `ShowConfiguration` 实例。 |

### UnityAdsShowOptions##unityadsshowoptions

> **Warning:**
>
> **在 4.19.0 版本中已弃用\*\*\*\*在 5.0.0 版本中计划移除。**
>
> 改用 [`ShowConfiguration.Builder`](/ads-android/4.19.0/sdk-integration/api/android-api.md#showconfiguration.builder)。有关迁移详情，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`UnityAdsShowOptions` 是之前用于指定广告展示选项的类。

## TokenConfiguration##tokenconfiguration

一个包含生成竞价令牌设置的类。

| **参数**          | **描述**                                     | **必需** |
| --------------- | ------------------------------------------ | ------ |
| `adFormat`      | 用于生成令牌的广告格式（例如 `REWARDED`、`INTERSTITIAL`）。 | 是      |
| `mediationInfo` | 一个包含有关聚合合作伙伴信息的对象。请参阅 `MediationInfo`。     | 否      |
| `extras`        | 一个包含额外键值参数的映射。                             | 否      |

1. **Kotlin**

   ```kotlin
   val tokenConfig = TokenConfiguration.Builder(AdFormat.REWARDED)
       .withMediationInfo(mediationInfo)
       .withExtras(extras)
       .build()
   ```

2. **Java**

   ```java
   TokenConfiguration tokenConfig = new TokenConfiguration.Builder(AdFormat.REWARDED)
       .withMediationInfo(mediationInfo)
       .withExtras(extras)
       .build();
   ```

### TokenConfiguration.Builder##tokenconfiguration.builder

用于创建 `TokenConfiguration` 实例的构建器类。

#### 构造函数##constructor

```kotlin
Builder(adFormat：AdFormat)
```

| **参数**     | **描述**                                                   | **必需** |
| ---------- | -------------------------------------------------------- | ------ |
| `adFormat` | 用于生成令牌的 AdFormat（例如 `REWARDED`、`INTERSTITIAL`、`BANNER`）。 | 是      |

**返回**：一个新的 `TokenConfiguration.Builder` 实例。

#### 构建器方法##builder-methods

| **方法**                             | **参数**                           | **必需**           | **返回**               | **描述**                                 |
| ---------------------------------- | -------------------------------- | ---------------- | -------------------- | -------------------------------------- |
| `withMediationInfo(MediationInfo)` | `mediationInfo`：包含有关聚合合作伙伴信息的对象。 | `No`             | `Builder`            | 设置聚合信息并返回构建器以进行链式调用。                   |
| `withExtras(Map<String, String>)`  | `extras`：附加键值参数的映射。              | `No`             | `Builder`            | 设置额外映射并返回构建器以进行链式调用。                   |
| `build()`                          | None                             | `Not applicable` | `TokenConfiguration` | 创建并返回带有已配置参数的 `TokenConfiguration` 实例。 |

### getToken##gettoken

根据提供的 `TokenConfiguration` 获取竞价令牌，并将其传递给令牌监听器。

| **参数**          | **描述**                                         | **必需** |
| --------------- | ---------------------------------------------- | ------ |
| `configuration` | 一个 `TokenConfiguration` 对象，用于指定广告格式、聚合信息和其他参数。 | 是      |
| `listener`      | 一个监听器，在令牌成功获取时调用并传入该令牌；如果发生错误，则返回 null。        | 是      |

**返回**：`Unit` (void) - 这是一个立即返回的异步方法。结果通过 `TokenListener` 回调提供。

1. **Kotlin**

   ```kotlin
   UnityAds.getToken(tokenConfig, listener)
   ```

2. **Java**

   ```java
   UnityAds.getToken(tokenConfig, listener);
   ```

## UnityAds##unityads

UnityAds 类是一个静态类，作为 SDK 的主要入口点。它处理初始化、令牌检索，并提供对全局 SDK 属性的访问。

### 静态变量##static-variables

#### isInitialized##isinitialized

一个用于确定 Unity Ads SDK 是否已成功初始化的布尔属性。

**返回**：如果 Unity Ads SDK 已成功初始化，则为 true。

1. **Kotlin**

   ```kotlin
   val isInitialized = UnityAds.isInitialized
   ```

2. **Java**

   ```java
   boolean isInitialized = UnityAds.isInitialized();
   ```

#### version##version

一个返回当前 Unity Ads SDK 版本的字符串属性。

**返回**：当前安装的 Unity Ads SDK 版本。

1. **Kotlin**

   ```kotlin
   val sdkVersion = UnityAds.version
   ```

2. **Java**

   ```java
   String sdkVersion = UnityAds.getVersion();
   ```

#### userIdentifier##useridentifier

一个表示您应用中每个用户唯一 ID 的字符串属性。

**返回**：当前值。

1. **Kotlin**

   ```kotlin
   UnityAds.userIdentifier = "my-user-id"
   ```

2. **Java**

   ```java
   UnityAds.userIdentifier = "my-user-id";
   ```

### 隐私##privacy

使用以下方法设置隐私和用户同意标志，以帮助您遵守受支持的隐私法规。

#### setUserConsent()##setuserconsent()

显示用户针对个性化广告的选择。

#### setUserOptOut()##setuseroptout()

为用户提供选择退出数据收集和个性化广告的选项。

#### setNonBehavioral()##setnonbehavioral()

启用情境（非个性化）广告的展示。

1. **Kotlin**

   ```kotlin
   UnityAds.userConsent = true

   UnityAds.userOptOut = false

   UnityAds.nonBehavioral = false
   ```

2. **Java**

   ```java
   UnityAds.setUserConsent(true);

   UnityAds.setUserOptOut(false);

   UnityAds.setNonBehavioral(false);
   ```

### MetaData##metadata

> **Warning:**
>
> \*\*已弃用（版本 4.19.0）**计划在 5.0.0 版本中移除。**
>
> 请在 [`UnityAds`](/ads-android/4.19.0/sdk-integration/api/android-api.md#unityads) 上使用类型化的隐私方法：`setUserConsent()`、`setUserOptOut()` 和 `setNonBehavioral()`。有关迁移的详细信息，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`MetaData` 是之前用于设置 GDPR 和其他隐私相关标志的类。

## UnityAdsError##unityadserror

```kotlin
class UnityAdsError internal constructor(
    val code:整型,
    val message:字符串
)
```

Unity Ads 在出现错误时返回的异常。

| **参数**            | **描述**    |
| ----------------- | --------- |
| `message: String` | 与错误相关的消息。 |
| `code: Int`       | 错误代码。     |

### BannerErrorCode##bannererrorcode

> **Warning:**
>
> \*\*已弃用（版本 4.19.0）**计划在 5.0.0 版本中移除。**
>
> 改用 `UnityAdsError`。有关迁移的详细信息，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`BannerErrorCode` 是之前用于横幅广告特定错误代码的枚举。

### BannerErrorInfo##bannererrorinfo

> **Warning:**
>
> \*\*已弃用（版本 4.19.0）**计划在 5.0.0 版本中移除。**
>
> 改用 `UnityAdsError`。有关迁移的详细信息，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`BannerErrorInfo` 是之前用于封装横幅广告错误详细信息的类。

### UnityAds.UnityAdsInitializationError##unityads.unityadsinitializationerror

> **Warning:**
>
> \*\*已弃用（版本 4.19.0）**计划在 5.0.0 版本中移除。**
>
> 改用 `UnityAdsError`。有关迁移的详细信息，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`UnityAds.UnityAdsInitializationError` 是之前用于初始化错误类型的嵌套枚举类型。

### UnityAds.UnityAdsLoadError##unityads.unityadsloaderror

> **Warning:**
>
> \*\*已弃用（版本 4.19.0）\*\***计划在 5.0.0 版本中移除。**
>
> 改用 `UnityAdsError`。有关迁移的详细信息，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`UnityAds.UnityAdsLoadError` 是之前用于加载错误类型的嵌套枚举类型。

### UnityAds.UnityAdsShowError##unityads.unityadsshowerror

> **Warning:**
>
> \*\*已弃用（版本 4.19.0）\*\***计划在 5.0.0 版本中移除。**
>
> 改用 `UnityAdsError`。有关迁移的详细信息，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`UnityAds.UnityAdsShowError` 是之前用于展示错误类型的嵌套枚举类型。

## 接口##interfaces

### BannerLoadListener##bannerloadlistener

用于处理 `BannerAd` 加载结果的接口。当横幅广告加载请求完成时，将调用此监听器，并提供成功加载的 `BannerAd` 实例或错误。

#### 方法签名##method-signature

```kotlin
fun interface BannerLoadListener {
    fun onBannerLoaded(bannerAd:BannerAd?, error:UnityAdsError?)
}
```

| **方法**           | **参数**                                                                                                 | **描述**                          |
| ---------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------- |
| `onBannerLoaded` | `bannerAd`：如果成功，则返回已加载的 `BannerAd` 实例；如果加载失败，则返回 null。`error`：返回描述失败的 `UnityAdsError`；如果加载成功，则返回 null。 | 在横幅广告加载请求完成时调用。正好只有一个参数不为 null。 |

1. **Kotlin**

   ```kotlin
   val bannerLoadListener = BannerLoadListener { bannerAd, error ->
       if (bannerAd != null) {
           // 横幅已成功加载
           this.bannerAd = bannerAd
           // 将 banner.view 添加到您的视图层级中
       } else {
           // 处理加载错误
           Log.e(\"UnityAds\", \"Banner load failed: ${error?.message}\")
       }
   }
   ```

2. **Java**

   ```java
   BannerLoadListener bannerLoadListener = (bannerAd, error) -> {
       if (bannerAd != null) {
           // 横幅已成功加载
           this.bannerAd = bannerAd;
           // 将 banner.getView() 添加到您的视图层级中
       } else {
           // 处理加载错误
           Log.e(\"UnityAds\", \"Banner load failed: \" + error.getMessage());
       }
   };
   ```

### BannerShowListener##bannershowlistener

用于处理 `BannerAd` 显示生命周期事件的接口。此监听器在横幅广告显示生命周期的各个阶段被调用。

#### 方法签名##method-signatures

```kotlin
interface BannerShowListener {
    fun onBannerShown(bannerAd:BannerAd)
    fun onBannerClicked(bannerAd:BannerAd)
    fun onBannerFailedToShow(bannerAd:BannerAd, error:UnityAdsError)
}
```

| **方法**                 | **参数**                                                          | **描述**           |
| ---------------------- | --------------------------------------------------------------- | ---------------- |
| `onBannerShown`        | `bannerAd`：已显示的 `BannerAd` 实例。                                  | 横幅广告成功显示在屏幕上时调用。 |
| `onBannerClicked`      | `bannerAd`：被点击的 `BannerAd` 实例。                                  | 用户点击横幅广告时调用。     |
| `onBannerFailedToShow` | `bannerAd`：显示失败的 `BannerAd` 实例。`error`：描述失败原因的 `UnityAdsError`。 | 横幅广告显示失败时调用。     |

1. **Kotlin**

   ```kotlin
   val bannerShowListener = object :BannerShowListener {
       override fun onBannerShown(bannerAd:BannerAd) {
           Log.d(\"UnityAds\", \"Banner shown\")
       }

       override fun onBannerClicked(bannerAd:BannerAd) {
           Log.d(\"UnityAds\", \"Banner clicked\")
       }

       override fun onBannerFailedToShow(bannerAd:BannerAd, error:UnityAdsError) {
           Log.e(\"UnityAds\", \"Banner failed to show: ${error.message}\")
       }
   }
   ```

2. **Java**

   ```java
   BannerShowListener bannerShowListener = new BannerShowListener() { }
       @Override
       public void onBannerShown(BannerAd bannerAd) {
           Log.d(\"UnityAds\", \"Banner shown\");
       }

       @Override
       public void onBannerClicked(BannerAd bannerAd) {
           Log.d("UnityAds", "Banner clicked");
       }

       @Override
       public void onBannerFailedToShow(BannerAd bannerAd, UnityAdsError error) {
           Log.e("UnityAds", "Banner failed to show: " + error.getMessage());
       }
   };
   ```

### InitializationListener##initializationlistener

用于接收有关 SDK 初始化状态回调的接口。当 SDK 初始化过程完成时，将调用此监听器。

#### 方法签名##method-signature

```kotlin
fun interface InitializationListener {
    fun onInitializationComplete(error:UnityAdsError?)
}
```

| **方法**                     | **参数**                                        | **描述**                                   |
| -------------------------- | --------------------------------------------- | ---------------------------------------- |
| `onInitializationComplete` | `error`：描述失败的 `UnityAdsError`，如果初始化成功则为 null。 | 当 SDK 初始化完成时调用。如果 error 为 null，则表示初始化成功。 |

1. **Kotlin**

   ```kotlin
   val listener = InitializationListener { error ->
       if (error == null) {
           Log.d(\"UnityAds\", \"SDK initialized successfully.\")
       } else {
           Log.e("UnityAds", "SDK 初始化失败: ${error.message}")
       }
   }
   ```

2. **Java**

   ```java
   InitializationListener listener = error -> {
       if (error == null) {
           Log.d("UnityAds", "SDK 初始化成功。");
       } else {
           Log.e("UnityAds", "SDK 初始化失败: " + error.getMessage());
       }
   };
   ```

### IUnityAdsInitializationListener##iunityadsinitializationlistener

> **Warning:**
>
> **在版本 4.19.0中已弃用\*\*\*\*计划在版本 5.0.0中移除**
>
> 改用 [`InitializationListener`](/ads-android/4.19.0/sdk-integration/api/android-api.md#initializationlistener)。有关迁移详情，请参阅 [Android 已弃用 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`IUnityAdsInitializationListener` 是之前用于 SDK 初始化的回调接口。

### InterstitialLoadListener##interstitialloadlistener

用于处理 `InterstitialAd` 加载结果的接口。当插屏广告加载请求完成时，将调用此监听器，并提供成功加载的 `InterstitialAd` 实例或错误信息。

#### 方法签名##method-signature

```kotlin
fun interface InterstitialLoadListener {
    fun onInterstitialLoaded(interstitialAd:InterstitialAd?, error:UnityAdsError?)
}
```

| **方法**                 | **参数**                                                                                                        | **描述**                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `onInterstitialLoaded` | `interstitialAd`：如果成功，则为已加载的 `InterstitialAd` 实例；如果加载失败，则为 null。`error`：描述失败的 `UnityAdsError`；如果加载成功，则为 null。 | 当插屏广告加载请求完成时调用。参数中恰好有一个将为非空值。 |

1. **Kotlin**

   ```kotlin
   val interstitialLoadListener = InterstitialLoadListener { interstitialAd, error ->
       if (interstitialAd != null) {
           // 插屏广告加载成功
           this.interstitialAd = interstitialAd
           // 您现在可以展示广告了
       } else {
           // 处理加载错误
           Log.e("UnityAds", "插屏加载失败: ${error?.message}")
       }
   }
   ```

2. **Java**

   ```java
   InterstitialLoadListener interstitialLoadListener = (interstitialAd, error) -> {
       if (interstitialAd != null) {
           // 插屏广告加载成功
           this.interstitialAd = interstitialAd;
           // 您现在可以展示广告了
       } else {
           // 处理加载错误
           Log.e("UnityAds", "插屏加载失败: " + error.getMessage());
       }
   };
   ```

### RewardedLoadListener##rewardedloadlistener

用于处理 `RewardedAd` 加载结果的接口。当激励广告加载请求完成时，将调用此监听器，并提供成功加载的 `RewardedAd` 实例或错误。

#### 方法签名##method-signature

```kotlin
fun interface RewardedLoadListener {
    fun onRewardedLoaded(rewardedAd:RewardedAd?, error:UnityAdsError?)
}
```

| **方法**             | **参数**                                                                                        | **描述**                          |
| ------------------ | --------------------------------------------------------------------------------------------- | ------------------------------- |
| `onRewardedLoaded` | `rewardedAd`：加载成功的 `RewardedAd` 实例，如果加载失败则为 null。`error`：描述失败的 `UnityAdsError`，如果加载成功则为 null。 | 当激励广告加载请求完成时调用。参数中恰好有一个不为 null。 |

1. **Kotlin**

   ```kotlin
   val rewardedLoadListener = RewardedLoadListener { rewardedAd, error ->
       if (rewardedAd != null) {
           // 激励广告加载成功
           this.rewardedAd = rewardedAd
           // 您现在可以展示广告
       } else {
           // 处理加载错误
           Log.e(\"UnityAds\", \"激励广告加载失败：${error?.message}\")
       }
   }
   ```

2. **Java**

   ```java
   RewardedLoadListener rewardedLoadListener = (rewardedAd, error) -> {
       if (rewardedAd != null) {
           // 激励广告加载成功
           this.rewardedAd = rewardedAd;
           // 您现在可以展示广告
       } else {
           // 处理加载错误
           Log.e(\"UnityAds\", \"Rewarded ad load failed: \" + error.getMessage());
       }
   };
   ```

### IUnityAdsLoadListener##iunityadsloadlistener

> **Warning:**
>
> **已在 4.19.0 版本中弃用**计划在 5.0.0 版本中移除。\*\*
>
> 请改用 [`InterstitialLoadListener`](/ads-android/4.19.0/sdk-integration/api/android-api.md#interstitialloadlistener) 或 [`RewardedLoadListener`](/ads-android/4.19.0/sdk-integration/api/android-api.md#rewardedloadlistener)。有关迁移详情，请参阅 [Android deprecated APIs](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`IUnityAdsLoadListener` 是之前的广告加载回调接口。

### ShowListener##showlistener

用于处理 `ShowAd` 或 `RewardedAd` 展示生命周期事件的接口。此通用接口为广告展示生命周期的各个阶段提供回调。

#### 方法签名##method-signatures

```kotlin
interface ShowListener<T> {
    fun onStarted(unityAd:T)
    fun onClicked(unityAd:T)
    fun onCompleted(unityAd:T, state:ShowFinishState)
    fun onFailed(unityAd:T, error:UnityAdsError)
}

interface InterstitialShowListener：ShowListener<InterstitialAd>

// Specialized listener for RewardedAd with reward callback
interface RewardedShowListener：ShowListener<RewardedAd> {
    fun onRewarded(unityAd:RewardedAd)
}
```

| **方法**                                | **参数**                                                                       | **描述**                                     |
| ------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------ |
| `onStarted`                           | `unityAd`：开始显示的广告实例（`InterstitialAd` 或 `RewardedAd`）。                        | 当广告开始在屏幕上显示时调用。                            |
| `onClicked`                           | `unityAd`：被点击的广告实例。                                                          | 当用户点击广告时调用。                                |
| `onCompleted`                         | `unityAd`：已完成的广告实例。`state`：`ShowFinishState`，指示广告是 `COMPLETED` 还是 `SKIPPED`。 | 当广告结束显示时调用。对于激励广告，`COMPLETED` 状态表示用户应获得奖励。 |
| `onFailed`                            | `unityAd`：未能显示的广告实例。`error`：`UnityAdsError`，描述失败原因。                          | 当广告未能显示时调用。                                |
| `onRewarded`（仅限 RewardedShowListener） | `unityAd`：应授予奖励的 `RewardedAd` 实例。                                            | 当用户通过观看激励广告至结束而获得奖励时调用。                    |

1. **Kotlin**

   ```kotlin
   val interstitialListener = object :InterstitialShowListener {
      override fun onStarted(unityAd:InterstitialAd) {
        // 执行某些操作
      }

      override fun onClicked(unityAd:InterstitialAd) {
        // Do something
      }

      override fun onCompleted(unityAd:InterstitialAd, state:ShowFinishState) {
        // Do something
      }

      override fun onFailed(unityAd:InterstitialAd, error:UnityAdsError) {
        // Do something
      }
   }

   val rewardedListener = object :RewardedShowListener {
      override fun onStarted(unityAd:RewardedAd) {
        // Do something
      }

      override fun onClicked(unityAd:RewardedAd) {
        // Do something
      }

      override fun onCompleted(unityAd:RewardedAd, state:ShowFinishState) {
        // Do something
      }

      override fun onFailed(unityAd:RewardedAd, error:UnityAdsError) {
        // Do something
      }

      override fun onRewarded(unityAd:RewardedAd) {
        // Do something
      }
   }
   ```

2. **Java**

   ```java
   ShowListener<InterstitialAd> interstitialListener = new InterstitialShowListener() { }
       @Override
       public void onStarted(InterstitialAd unityAd) {
           // 执行某些操作
       }

       @Override
       public void onClicked(InterstitialAd unityAd) {
           // Do something
       }

       @Override
       public void onCompleted(InterstitialAd unityAd, ShowFinishState state) {
           // Do something
       }

       @Override
       public void onFailed(InterstitialAd unityAd, UnityAdsError error) {
           // Do something
       }
   };

   ShowListener<RewardedAd> rewardedListener = new RewardedShowListener() { }
       @Override
       public void onStarted(RewardedAd unityAd) {
           // Do something
       }

       @Override
       public void onClicked(RewardedAd unityAd) {
           // Do something
       }

       @Override
       public void onCompleted(RewardedAd unityAd, ShowFinishState state) {
           // Do something
       }

       @Override
       public void onFailed(RewardedAd unityAd, UnityAdsError error) {
           // Do something
       }

       @Override
       public void onRewarded(RewardedAd unityAd) {
           // Do something
       }
   };
   ```

### IUnityAdsShowListener##iunityadsshowlistener

> **Warning:**
>
> **已在 4.19.0 版本中弃用**计划在 5.0.0 版本中移除。\*\*
>
> 改用 [`ShowListener`](/ads-android/4.19.0/sdk-integration/api/android-api.md#showlistener)。有关迁移详情，请参阅 [Android 已弃用的 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`IUnityAdsShowListener` 是之前用于广告展示事件的回调接口。

### TokenListener##tokenlistener

用于接收 `getToken` 调用结果的接口。当竞价令牌请求完成时，将调用此监听器。

#### 方法签名##method-signature

```kotlin
fun interface TokenListener {
    fun onTokenReady(token:String?)
}
```

| **方法**         | **参数**                                      | **描述**                                  |
| -------------- | ------------------------------------------- | --------------------------------------- |
| `onTokenReady` | `token`：如果成功，则为字符串形式的竞价令牌；如果令牌生成失败，则为 null。 | 在令牌请求完成时调用。应将该令牌传递给您的中介合作伙伴的 SDK 以进行竞价。 |

1. **Kotlin**

   ```kotlin
   val listener = TokenListener { token ->
       if (token != null) {
           // 将令牌传递给您的中介合作伙伴的 SDK
           Log.d(\"UnityAds\", \"Token received: $token\")
       } else {
           // 处理令牌检索失败
           Log.e(\"UnityAds\", \"Token retrieval failed\")
       }
   }
   ```

2. **Java**

   ```java
   TokenListener listener = token -> {
       if (token != null) {
           // 将令牌传递给您的中介合作伙伴的 SDK
           Log.d("UnityAds", "Token received: " + token);
       } else {
           // 处理令牌检索失败
           Log.e("UnityAds", "Token retrieval failed");
       }
   };
   ```

### onAdExpired##onadexpired

`InterstitialAd` 和 `RewardedAd` 实例上可用的方法，允许您注册回调以处理广告过期事件。当广告不再有效且不应显示时，将触发此回调。

#### 方法签名##method-signature

```kotlin
// On InterstitialAd
var onAdExpired：AdExpiredListener?
// On RewardedAd
var onAdExpired：AdExpiredListener?

fun interface AdExpiredListener {
    fun onAdExpired(ad:T) // T 是 InterstitialAd 或 RewardedAd
}
```

| **参数**     | **描述**                        |
| ---------- | ----------------------------- |
| `callback` | **(必需)** 一个在广告过期时接收过期广告实例的函数。 |

**返回**：`Unit` (void) - 此方法注册回调并立即返回。

1. **Kotlin**

   ```kotlin
   // 对于 InterstitialAd
   interstitialAd.onAdExpired = AdExpiredListener { ad ->
       // 处理广告过期 - 加载新广告
       Log.d("UnityAds", "插屏广告过期")
       // 加载新广告
   }

   // For RewardedAd
   rewardedAd.onAdExpired = AdExpiredListener { ad ->
       // Handle ad expiration - load a new ad
       Log.d("UnityAds", "激励广告过期")
       // Load a new ad
   }
   ```

2. **Java**

   ```java
   // 对于 InterstitialAd
   interstitialAd.setOnAdExpired(ad -> {
       // 处理广告过期 - 加载新广告
       Log.d("UnityAds", "插屏广告过期");
       // 加载新广告
   });

   // For RewardedAd
   rewardedAd.setOnAdExpired(ad -> {
       // Handle ad expiration - load a new ad
       Log.d("UnityAds", "Rewarded ad expired");
       // Load a new ad
   });
   ```

## 枚举##enums

### AdFormat##adformat

不同广告格式的枚举类型。

| **值**          | **描述**                   |
| -------------- | ------------------------ |
| `INTERSTITIAL` | 在应用自然中断时显示的全屏广告，几秒钟后可跳过。 |
| `REWARDED`     | 用户选择观看以换取应用内奖励的全屏广告。     |
| `BANNER`       | 占据屏幕一部分的广告，通常位于顶部或底部。    |

### LogLevel##loglevel

不同日志详细程度的枚举类型。

| **值**      | **描述**                             |
| ---------- | ---------------------------------- |
| `DISABLED` | 不应打印与 Unity Ads 相关的日志。             |
| `INFO`     | 默认级别。显示标准集成和Lifecycle消息。           |
| `DEBUG`    | 显示用于调试的详细日志。                       |
| `ERROR`    | 来自初始化/加载/展示操作的基本错误，以及开发者必须注意的关键故障。 |

### ShowFinishState##showfinishstate

描述广告展示后最终状态的枚举类型。

| **值**       | **描述**                            |
| ----------- | --------------------------------- |
| `SKIPPED`   | 用户在广告播放结束前跳过了广告。                  |
| `COMPLETED` | 广告已完整播放。对于 `RewardedAd`，此状态会触发奖励。 |

### UnityAds.UnityAdsShowCompletionState##unityads.unityadsshowcompletionstate

> **Warning:**
>
> **已在 4.19.0 版本中弃用。计划在 5.0.0 版本中移除。**
>
> 改用 [`ShowFinishState`](/ads-android/4.19.0/sdk-integration/api/android-api.md#showfinishstate)。有关迁移详情，请参阅 [Android 已弃用的 API](/ads-android/4.19.0/sdk-integration/api/android-deprecated-apis.md)。

`UnityAds.UnityAdsShowCompletionState` 是之前用于广告展示最终状态的嵌套枚举。