# Unity Ads iOS SDK API 参考 - Objective-C

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

在将 Unity Ads 集成到 iOS 应用程序时，请将此参考用于 Objective-C 中的 Unity Ads iOS SDK API。

使用此 API 之前，请确保已导入`UnityAds`库以便在 app 中启用 Monetization。请参阅[导入 UnityAds 库](/ads-ios/4.19.0/sdk-integration/import-library.md)以了解更多信息。

## 类##classes

## UADSBannerAd##uadsbannerad

`UADSBannerAd` 类管理横幅广告服务的加载和展示。

### load:completion:\_##load:completion:\_

1. **Objective-C**

   ```objective-c
   @interface UADSBannerAd :NSObject
   +（无效）加载：(UADSBannerLoadConfiguration * _Nonnull)config
     completion:(void (^ _Nonnull)(UADSBannerAd * _Nullable, id<UnityAdsError> _Nullable))complete;
   @end
   ```

加载具有指定配置的横幅广告。

| **参数** | **描述**                                                       |
| ------ | ------------------------------------------------------------ |
| 配置     | 加载横幅广告的选项。                                                   |
| 完成     | 加载横幅时调用的回调。如果成功，则返回加载的 BannerAd 实例，如果加载失败，则返回 UnityAdsError。 |

### 视图##view

1. **Objective-C**

   ```objective-c
   @interface UADSBannerAd :NSObject
   @property（非原子、只读、强）UIView * _Nonnull 视图；
   @end
   ```

用于访问横幅广告实例的视图属性。使用此属性可将横幅广告插入到app的现有视图层级视图视图中所需的位置。

### UADSBannerView##uadsbannerview

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 [`UADSBannerAd`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsbannerad)。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSBannerView` 是用于加载和显示横幅广告服务的上一类。

### UADSBannerViewDelegate##uadsbannerviewdelegate

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 [`UADSBannerAdDelegate`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsbanneraddelegate)。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSBannerViewDelegate` 是先前用于处理横幅广告事件的委托协议。

## UADSBannerLoadConfiguration##uadsbannerloadconfiguration

`UADSBannerLoadConfiguration` 类封装了加载横幅广告服务所需的选项。这包括指定放置/位置 ID、横幅大小、可选广告标记、可选委托以及任何其他参数。

1. **Objective-C**

   ````objective-c
   @interface BannerLoadConfiguration：NSObject
   @property（非原子、强） NSString *placementId;
   @property（非原子、强、可 null） NSString *adMarkup;
   @property（非原子、赋值） CGSize bannerSize;
   @property (nonatomic, weak, nullable) id<UADSBannerAdDelegate> 委托； @property (nonatomic, strong, nullable) NSString *mediationAdUnitId; @property (nonatomic, strong, nullable) MediationInfo *mediationInfo; @property (nonatomic, strong) NSDictionary<nsstring *, nsstring *>
   *extras; @end ```
   </Tab>
   </Tabs>

   <Table>
   <TableHeader>
   <TableRow>
     <TableHeaderCell>**属性**</TableHeaderCell>
     <TableHeaderCell>**描述**</TableHeaderCell>
     <TableHeaderCell>**必需**</TableHeaderCell>
   </TableRow>
   </TableHeader>

   <TableBody>
   <TableRow>
     <TableCell>`placementId`</TableCell>
     <TableCell>Unity Monetization（变现）后台中定义的放置/位置 ID。</TableCell>
     <TableCell>是</TableCell>
   </TableRow>

   <TableRow>
     <TableCell>`adMarkup`</TableCell>
     <TableCell>通过竞价加载广告时使用的广告标记数据。</TableCell>
     <TableCell>否</TableCell>
   </TableRow>

   <TableRow>
     <TableCell>`bannerSize`</TableCell>
     <TableCell>横幅广告的大小。</TableCell>
     <TableCell>是</TableCell>
   </TableRow>

   <TableRow>
     <TableCell>`delegate`</TableCell>
     <TableCell>委托处理横幅广告事件。</TableCell>
     <TableCell>是</TableCell>
   </TableRow>

   <TableRow>
     <TableCell>`mediationAdUnitId`</TableCell>
     <TableCell>聚合合作伙伴后台中定义的广告单元或放置/位置 ID。</TableCell>
     <TableCell>否</TableCell>
   </TableRow>

   <TableRow>
     <TableCell>`mediationInfo`</TableCell>
     <TableCell>指定有关聚合集成的详细信息。</TableCell>
     <TableCell>否</TableCell>
   </TableRow>

   <TableRow>
     <TableCell>`extras`</TableCell>
     <TableCell>其他自定义键值对。</TableCell>
     <TableCell>否</TableCell>
   </TableRow>
   </TableBody>
   </Table>

   ## UADSBannerLoadConfigurationBuilder##uadsbannerloadconfigurationbuilder

   使用 `UADSBannerLoadConfigurationBuilder` 创建并返回 `UADSBannerLoadConfiguration` 类的实例。

   ### initWithPlacementId:adMarkup:bannerSize:delegate##initwithplacementid:admarkup:bannersize:delegate

   <Tabs>
   <Tab title="Objective-C">
   ```objective-c
   - (nonnull instancetype)initWithPlacementId:(NSString * _Nonnull)placementId
                                    bannerSize：(CGSize)bannerSize
                                      delegate:(id <UADSBannerAdDelegate> _Nonnull)delegate;
   ````

创建新的 `BannerLoadConfigurationBuilder` 实例。

| **属性**        | **描述**                                | **必需** |
| ------------- | ------------------------------------- | ------ |
| `placementId` | Unity Monetization（变现）后台中定义的放置/位置 ID。 | 是      |
| `bannerSize`  | 横幅广告的大小。                              | 是      |
| `delegate`    | 委托处理横幅广告事件。                           | 是      |

**返回**：`UADSBannerLoadConfigurationBuilder` 实例。

### withAdMarkup:\_##withadmarkup:\_

1. **Objective-C**

   ```objective-c
   -（非 null 实例类型）withAdMarkup：（NSString * _Nonnull）adMarkup
   ```

向`UADSBannerLoadConfigurationBuilder`添加 adMarkup。

| **参数**   | **描述**              |
| -------- | ------------------- |
| adMarkup | 通过竞价加载广告时使用的广告标记数据。 |

### withMediationAdUnitId:\_##withmediationadunitid:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withMediationAdUnitId:(NSString * _Nonnull)mediationAdUnitId
   ```

向`UADSBannerLoadConfigurationBuilder`添加聚合广告单元 ID。

| **参数**            | **描述**                     |
| ----------------- | -------------------------- |
| mediationAdUnitId | 聚合合作伙伴后台中定义的广告单元或放置/位置 ID。 |

**返回**：更新的`UADSBannerLoadConfigurationBuilder`实例。

### withMediationInfo:\_##withmediationinfo:\_

1. **Objective-C**

   ```objective-c
   -（非 null 实例类型）withMediationInfo：(UADSMediationInfo * _Nonnull)info
   ```

向`UADSBannerLoadConfigurationBuilder`添加聚合信息。

| **参数**        | **描述**                    |
| ------------- | ------------------------- |
| mediationInfo | 有关聚合集成的详细信息（名称、版本、适配器版本）。 |

**返回**：更新了 UADSBannerLoadConfigurationBuilder 实例。

### withExtras:\_##withextras:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
   ```

向`UADSBannerLoadConfigurationBuilder`添加额外的键值参数。

| **参数** | **描述**      |
| ------ | ----------- |
| extras | 横幅加载的自定义参数。 |

**返回**：更新的`UADSBannerLoadConfigurationBuilder`实例。

### 版本##build

1. **Objective-C**

   ```objective-c
   - (UADSBannerLoadConfiguration * _Nonnull) 构建
   ```

构建并返回 `UADSBannerLoadConfiguration` 实例。

**返回**：`UADSBannerLoadConfiguration` 实例。

### UADSBannerLoadOptions##uadsbannerloadoptions

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 改用 [`UADSBannerLoadConfiguration`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsbannerloadconfiguration) 和 [`UADSBannerLoadConfigurationBuilder`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md) 。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSBannerLoadOptions` 是指定横幅加载选项的上一类。

## UADSInitializationConfiguration##uadsinitializationconfiguration

1. **Objective-C**

   ```objective-c
   @interface UADSInitializationConfiguration: NSObject
   @property (nonatomic, strong) NSString *gameId;
   @property (nonatomic, assign) BOOL isTestModeEnabled;
   @property (nonatomic, assign) UADSLogLevel logLevel;
   @property (nonatomic, strong, nullable) UADSMediationInfo *mediationInfo;
   @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras;
   @end
   ```

`UADSInitializationConfiguration` 类创建一个对象，其中包含初始化 Unity Ads SDK 所需的 app 基本信息。

| **属性**              | **类型**                                         | **描述**          | **必需** |
| ------------------- | ---------------------------------------------- | --------------- | ------ |
| `gameId`            | `NSString *`                                   | Unity 项目的唯一标识符。 | 是      |
| `isTestModeEnabled` | `BOOL`                                         | 启用或禁用测试模式。      | 否      |
| `logLevel`          | `UADSLogLevel`                                 | 指定日志输出的细节级别。    | 否      |
| `mediationInfo`     | `UADSMediationInfo * _Nullable`                | 指定有关聚合集成的详细信息。  | 否      |
| `extras`            | `NSDictionary&lt;NSString *, NSString *&gt; *` | 用于自定义配置的其他键值对。  | 否      |

## UADSInitializationConfigurationBuilder##uadsinitializationconfigurationbuilder

使用 `UADSInitConfigurationBuilder` 创建并返回 `UADSInitializationConfiguration` 类的实例。

### initWithgameID:\_##initwithgameid:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)initWithGameId：(NSString * _Nonnull)gameId
   ```

创建新的 `UADSInitConfigurationBuilder` 实例。

| **参数** | **描述**                                  |
| ------ | --------------------------------------- |
| gameId | 游戏的唯一标识符，由 Unity Ads 管理工具或 Unity 编辑器提供。 |

**返回**：`UADSInitConfigurationBuilder` 实例。

### withTestMode:\_##withtestmode:\_

1. **Objective-C**

   ```objective-c
   - （非 null 实例类型）withTestMode：(BOOL)testMode
   ```

设置测试模式。

| **参数**   | **描述**                            |
| -------- | --------------------------------- |
| testMode | 将此标志设置为 `true` 可指示测试模式并仅显示测试广告服务。 |

**返回**：更新的`UADSInitConfigurationBuilder`实例。

### withLogLevel:\_##withloglevel:\_

1. **Objective-C**

   ```objective-c
   -（非 null 实例类型）withLogLevel：（枚举 UADSLogLevel）logLevel
   ```

设置[日志级别](#uadsloglevel)（定义日志中包含的细节量），从 None 到 Full 调试信息。

| **参数** | **描述**       |
| ------ | ------------ |
| 级别     | 指定日志输出的细节级别。 |

**返回**：更新的`UADSInitConfigurationBuilder`实例。

### withMediationInfo:\_##withmediationinfo:\_

1. **Objective-C**

   ```objective-c
   -（非 null 实例类型）withMediationInfo：(UADSMediationInfo * _Nonnull)info
   ```

设置聚合信息，提供有关 app 聚合集成的详细信息，包括聚合名称、版本和适配器版本。

| **参数** | **描述**         |
| ------ | -------------- |
| info   | 指定有关聚合集成的详细信息。 |

**返回**：更新的`UADSInitConfigurationBuilder`实例。

### withExtras:\_##withextras:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
   ```

设置其他参数。

| **参数** | **描述**         |
| ------ | -------------- |
| extras | 用于自定义配置的其他键值对。 |

**返回**：更新的`UADSInitConfigurationBuilder`实例。

### 版本##build

1. **Objective-C**

   ```objective-c
   - (UADSInitializationConfiguration * _Nonnull) 构建
   ```

构建并返回 UADSInitializationConfiguration 实例。

**返回**：`UADSInitializationConfiguration` 实例。

## UADSInterstitialAd##uadsinterstitialad

`UADSInterstitialAd` 类管理插页式广告服务的加载和展示。

### load:completion:\_##load:completion:\_

1. **Objective-C**

   ```objective-c
   @interface UADSInterstitialAd：NSObject
   +（无效）加载：(UADSLoadConfiguration * _Nonnull)configuration
     completion:(void (^ _Nonnull)(UADSInterstitialAd * _Nullable, id<UnityAdsError> _Nullable))complete;
   @end
   ```

加载具有指定配置的插页式广告。

| **参数** | **描述**                                    |
| ------ | ----------------------------------------- |
| 配置     | 包含广告加载选项的 UADSLoadConfiguration 实例。       |
| 完成     | 加载过程完成后调用的回调。返回 UADSInterstitialAd 实例或报错。 |

### show:delegate:\_##show:delegate:\_

1. **Objective-C**

   ```objective-c
   @interface UADSInterstitialAd：NSObject
   - (void)show：(UADSShowConfiguration * _Nullable)configuration
       delegate:(id <UADSInterstitialShowDelegate> _Nonnull)delegate;
   @end
   ```

显示加载的插页式广告。

| **参数**   | **描述**                                      |
| -------- | ------------------------------------------- |
| 配置       | 用于展示广告的可选配置。                                |
| delegate | 符合处理广告事件的`UADSInterstitialShowDelegate`的委托。 |

### onAdExpired##onadexpired

注册在广告到期时触发的回调。

1. **Objective-C**

   ```objective-c
   @interface UnityAd：NSObject
   @property (nonatomic, copy) void (^ _Nullable onAdExpired)(UnityAd * _Nonnull);
   @end
   ```

## UADSLoadConfiguration##uadsloadconfiguration

`UADSLoadConfiguration` 类封装了加载 Unity Ads 所需的选项。这包括指定放置/位置 ID、可选的广告标记以及任何其他参数。

1. **Objective-C**

   ```objective-c
   @interface UADSLoadConfiguration: NSObject
   @property (nonatomic, strong) NSString *placementId;
   @property (nonatomic, strong, nullable) NSString *adMarkup;
   @property (nonatomic, strong, nullable) NSString *mediationAdUnitId;
   @property (nonatomic, strong, nullable) UADSMediationInfo *mediationInfo;
   @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras;
   @end
   ```

创建新的 `UADSLoadConfiguration` 实例。

| **属性**              | **描述**                                | **必需** |
| ------------------- | ------------------------------------- | ------ |
| `placementId`       | Unity Monetization（变现）后台中定义的放置/位置 ID。 | 是      |
| `adMarkup`          | 通过竞价加载广告时使用的广告标记数据。                   | 否      |
| `mediationAdUnitId` | 聚合合作伙伴后台中使用的放置/位置 ID。                 | 否      |
| `mediationInfo`     | 指定有关聚合集成的详细信息。                        | 否      |
| `extras`            | 用于配置的其他自定义键值对。                        | 否      |

| \*\*注意：\*\*所有竞价实现都需要 adMarkup 属性。对于瀑布流实现，可将 adMarkup 设置为 nil。 |
| ------------------------------------------------------------- |

## UADSLoadConfigurationBuilder##uadsloadconfigurationbuilder

使用 `UADSLoadConfigurationBuilder` 创建并返回 `UADSLoadConfiguration` 类的实例。

### initWithPlacementId:\_##initwithplacementid:\_

1. **Objective-C**

   ```objective-c
   - - (nonnull instancetype)initWithPlacementId:(NSString * _Nonnull)placementId;
   ```

创建新的 `UADSLoadConfigurationBuilder` 实例。

| **参数**        | **描述**                                |
| ------------- | ------------------------------------- |
| `placementId` | Unity Monetization（变现）后台中定义的放置/位置 ID。 |

**返回**：`UADSLoadConfigurationBuilder` 实例。

### withAdMarkup:\_##withadmarkup:\_

1. **Objective-C**

   ```objective-c
   -（非 null 实例类型）withAdMarkup：（NSString * _Nonnull）adMarkup
   ```

向`UADSLoadConfigurationBuilder`添加 adMarkup。

| **属性**     | **描述**              |
| ---------- | ------------------- |
| `adMarkup` | 通过竞价加载广告时使用的广告标记数据。 |

**返回**：更新的`UADSLoadConfigurationBuilder`实例。

### withMediationAdUnitId:\_##withmediationadunitid:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withMediationAdUnitId:(NSString * _Nonnull)mediationAdUnitId
   ```

将聚合广告单元 ID 添加到`UADSLoadConfigurationBuilder`。

| **属性**              | **描述**                |
| ------------------- | --------------------- |
| `mediationAdUnitId` | 聚合合作伙伴后台中使用的放置/位置 ID。 |

**返回**：更新的`UADSLoadConfigurationBuilder`实例。

### withMediationInfo:\_##withmediationinfo:\_

1. **Objective-C**

   ```objective-c
   -（非 null 实例类型）withMediationInfo：(UADSMediationInfo * _Nonnull)info
   ```

向`UADSLoadConfigurationBuilder`添加聚合信息。

| **参数**        | **描述**                      |
| ------------- | --------------------------- |
| mediationInfo | 指定有关聚合集成的详细信息（名称、版本、适配器版本）。 |

**返回**：更新的`UADSLoadConfigurationBuilder`实例。

### withExtras:\_##withextras:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
   ```

向`UADSLoadConfigurationBuilder`添加额外的配置键值对。

| **参数** | **描述**           |
| ------ | ---------------- |
| extras | 用于广告加载的自定义参数的字典。 |

**返回**：更新的`UADSLoadConfigurationBuilder`实例。

### 版本##build

1. **Objective-C**

   ```objective-c
   - (UADSLoadConfiguration * _Nonnull) 构建
   ```

构建并返回 `UADSLoadConfiguration` 实例。

**返回**：`UADSLoadConfiguration` 实例。

### UADSLoadOptions##uadsloadoptions

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 [`UADSLoadConfigurationBuilder`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsloadconfigurationbuilder)。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSLoadOptions` 是用于指定广告加载选项的上一类。

## UADSMediationInfo##uadsmediationinfo

指定有关聚合集成的详细信息。

1. **Objective-C**

   ```objective-c
   @interface UADSMediationInfo：NSObject
   - (nonnull instancetype)initWithName：(NSString * _Nonnull)name
                                version：(NSString * _Nonnull)version
                         adapterVersion：(NSString * _Nonnull)adapterVersion
   @end
   ```

| **参数**         | **描述**                   |
| -------------- | ------------------------ |
| name           | app 中集成的聚合平台的名称。         |
| 版本             | app 中集成的聚合 SDK 版本。       |
| adapterVersion | 聚合合作伙伴的 Unity Ads 适配器版本。 |

**返回**：`UADSMediationInfo` 实例。

### UADSMediationMetaData##uadsmediationmetadata

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 [`UADSMediationInfo`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsmediationinfo)。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSMediationMetaData` 是传递聚合合作伙伴信息的上一类。

## UADSRewardedAd##uadsrewardedad

UADSRewardedAd 类管理奖励广告服务的加载和展示。

### load:completion:\_##load:completion:\_

1. **Objective-C**

   ```objective-c
   +（无效）加载：(UADSLoadConfiguration * _Nonnull)configuration
     completion:(void (^ _Nonnull)(UADSRewardedAd * _Nullable, id<UnityAdsError> _Nullable))complete;
   ```

加载具有指定选项的奖励广告。

| **参数** | **描述**                                                             |
| ------ | ------------------------------------------------------------------ |
| 配置     | 包含广告加载选项的 UADSLoadConfiguration 实例。                                |
| 完成     | 在广告加载完成后调用的回调。如果成功，则返回 UADSRewardedAd 实例，如果加载失败，则返回 UnityAdsError。 |

### show:delegate:\_##show:delegate:\_

1. **Objective-C**

   ```objective-c
   - (void)show：(UADSShowConfiguration * _Nullable)configuration
       delegate:(id <UADSRewardedShowDelegate> _Nonnull)delegate;
   ```

显示加载的奖励广告。

| **参数**   | **描述**       |
| -------- | ------------ |
| 配置       | 显示广告的可选设置。   |
| delegate | 处理奖励广告事件的委托。 |

### onAdExpired##onadexpired

注册在广告到期时触发的回调。

1. **Objective-C**

   ```objective-c
   @interface UnityAd：NSObject
   @property (nonatomic, copy) void (^ _Nullable onAdExpired)(UnityAd * _Nonnull);
   @end
   ```

## UADSShowConfiguration##uadsshowconfiguration

`UADSShowConfiguration` 类指定了在显示 Unity Ads 时要以键/值对形式通道的其他参数。

1. **Objective-C**

   ```objective-c
   @interface UADSShowConfigurationBuilder : NSObject
   @property (nonatomic, weak, nullable) UIViewController *viewController;
   @property (nonatomic, strong, nullable) NSString *customRewardString;
   @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras;
   @end
   ```

使用可选的附加参数创建一个新的`UADSShowConfiguration`实例。

| **属性**               | **描述**                   | **必需** |
| -------------------- | ------------------------ | ------ |
| `viewController`     | 用于展示广告的视图控制器。            | 否      |
| `customRewardString` | 广告展示的自定义奖励标识符。           | 否      |
| `extras`             | 在展示广告时要包含的其他键值参数。默认为空字典。 | 否      |

## UADSShowConfigurationBuilder##uadsshowconfigurationbuilder

使用 `UADSShowConfigurationBuilder` 创建并返回 `UADSShowConfiguration` 类的实例。

### init##init

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)init;
   ```

创建新的 `UADSShowConfigurationBuilder` 实例。

### withViewController:\_##withviewcontroller:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withViewController：(UIViewController * _Nonnull)viewController
   ```

设置展示广告的视图控制器。

| **参数**           | **描述**      |
| ---------------- | ----------- |
| `viewController` | 展示广告的视图控制器。 |

**返回**：更新的`UADSShowConfigurationBuilder`实例。

### withCustomRewardString:\_##withcustomrewardstring:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withCustomRewardString：(NSString * _Nonnull)customRewardString
   ```

为广告展示设置自定义奖励标识符。

| **参数**               | **描述**        |
| -------------------- | ------------- |
| `customRewardString` | 广告展示的唯一奖励 ID。 |

**返回**：更新的`ShowConfigurationBuilder`实例。

### withExtras:\_##withextras:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
   ```

在展示广告时添加额外的键值参数。

| **参数**   | **描述**      |
| -------- | ----------- |
| `extras` | 广告展示的自定义参数。 |

**返回**：更新的`UADSShowConfigurationBuilder`实例。

### 版本##build

1. **Objective-C**

   ```objective-c
   - (UADSShowConfiguration * _Nonnull) 构建
   ```

构建并返回 `UADSShowConfiguration` 实例。

**返回**：`UADSShowConfiguration` 实例。

### UADSShowOptions##uadsshowoptions

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 [`UADSShowConfigurationBuilder`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsshowconfigurationbuilder)。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSShowOptions` 是用于指定广告展示选项的上一类。

## UADSTokenConfiguration##uadstokenconfiguration

1. **Objective-C**

   ```objective-c
   @interface UADSTokenConfiguration : NSObject
   @property (nonatomic, assign) AdFormat UADSAdFormat;
   @property (nonatomic, strong, nullable) UADSMediationInfo *mediationInfo;
   @property (nonatomic, strong, nullable) NSString *mediationAdUnitId;
   @property (nonatomic, strong, nullable) NSString *placementId;
   @property (nonatomic, assign) CGSize bannerSize;
   @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras;
   @end
   ```

`UADSTokenConfiguration` 接口创建一个对象，其中包含获取竞价令牌所需的基本信息。

| **属性**              | **描述**                                | **必需** |
| ------------------- | ------------------------------------- | ------ |
| `adFormat`          | 指定广告格式的类型（插页式、奖励式、横幅广告）。              | 是      |
| `mediationInfo`     | 指定有关聚合集成的详细信息。                        | 否      |
| `mediationAdUnitId` | 聚合合作伙伴后台中使用的放置/位置 ID。                 | 否      |
| `placementId`       | Unity Monetization（变现）后台中定义的放置/位置 ID。 | 否      |
| `bannerSize`        | 横幅广告的大小（如果令牌请求横幅广告）。                  | 否      |
| `extras`            | 用于自定义配置的其他键值对。                        | 否      |

### UADSTokenConfigurationBuilder##uadstokenconfigurationbuilder

使用 `UADSTokenConfigurationBuilder` 创建并返回 `UADSTokenConfiguration` 类的实例。

### initWithAdFormat:\_##initwithadformat:\_

1. **Objective-C**

   ```objective-c
   -（非 null 实例类型）initWithAdFormat：（枚举 UADSAdFormat）adFormat
   ```

创建新的 `UADSTokenConfigurationBuilder` 实例。

| **参数**   | **描述**                            |
| -------- | --------------------------------- |
| adFormat | 指定广告类型（插页式、奖励式、横幅式）的 AdFormat 实例。 |

**返回**：`UADSTokenConfigurationBuilder` 实例。

### withMediationInfo:\_##withmediationinfo:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withMediationInfo：(UADSMediationInfo * _Nonnull)mediationInfo
   ```

指定有关聚合集成的详细信息。

| **参数**        | **描述**         |
| ------------- | -------------- |
| mediationInfo | 指定有关聚合集成的详细信息。 |

**返回**：更新的`TokenConfigurationBuilder`实例。

### withMediationAdUnitId:\_##withmediationadunitid:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withMediationAdUnitId:(NSString * _Nonnull)mediationAdUnitId
   ```

将聚合广告单元 ID 添加到`TokenConfiguration`。

| **属性**              | **描述**                |
| ------------------- | --------------------- |
| `mediationAdUnitId` | 聚合合作伙伴后台中使用的放置/位置 ID。 |

**返回**：更新的`UADSTokenConfigurationBuilder`实例。

### withPlacementId:\_##withplacementid:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withPlacementId：(NSString * _Nonnull)placementId
   ```

指定 Unity Monetization Dashboard（变现后台）中定义的放置/位置 ID。

| **参数**      | **描述**                                |
| ----------- | ------------------------------------- |
| placementId | Unity Monetization（变现）后台中定义的放置/位置 ID。 |

**返回**：更新的`UADSTokenConfigurationBuilder`实例。

### withBannerSize:\_##withbannersize:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withBannerSize：(CGSize)bannerSize
   ```

如果令牌请求横幅广告，指定横幅广告的大小。

| **参数**     | **描述**                |
| ---------- | --------------------- |
| bannerSize | 横幅广告的大小（如果有令牌请求横幅广告）。 |

**返回**：更新的`UADSTokenConfigurationBuilder`实例。

### withExtras:\_##withextras:\_

1. **Objective-C**

   ```objective-c
   - (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
   ```

指定用于自定义配置的其他键值对。

| **参数** | **描述**         |
| ------ | -------------- |
| extras | 用于自定义配置的其他键值对。 |

**返回**：更新的`UADSTokenConfigurationBuilder`实例。

### 版本##build

1. **Objective-C**

   ```objective-c
   - (UADSTokenConfiguration * _Nonnull) 构建
   ```

构建并返回 `UADSTokenConfiguration` 实例。

**返回**：`UADSTokenConfiguration` 实例。

## UnityAds##unityads

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

### 初始化##initialization

#### initialize(\_, completion:)##initialize(\_-completion:)

使用指定配置初始化 Unity Ads SDK。当初始化以成功或失败完成时，将调用完成代码块。

1. **Objective-C**

   ```objective-c
   + (void) initialize：(UADSInitializationConfiguration *) 配置
            completion:(void (^)(id<UnityAdsError> )) completion;
   ```

| **参数** | **描述**                                                |
| ------ | ----------------------------------------------------- |
| 配置     | UADSInitializationConfiguration 对象，其中包含初始化 SDK 所需的设置。 |
| 完成     | SDK 初始化完成后调用的回调。如果初始化失败，则返回 UnityAdsError。            |

### GetToken##gettoken

#### getToken(\_, completion:)##gettoken(\_-completion:)

根据提供的`UADSTokenConfiguration`获取竞价令牌并将其传递给完成代码块。

1. **Objective-C**

   ```objective-c
   + (void) getToken：(UADSTokenConfiguration *) 配置
          completion:(void (^)(NSString * )) completion;
   ```

| **参数** | **描述**                                         |
| ------ | ---------------------------------------------- |
| 配置     | 一个`UADSTokenConfiguration`对象，指定广告格式、聚合信息和其他参数。 |
| 完成     | 如果已成功获取，则使用令牌调用完成代码块，如果发生报错，则为 null。           |

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

#### IsInitialized##isinitialized

确定 Unity Ads SDK 是否已成功初始化。

1. **Objective-C**

   ```objective-c
   + (BOOL)isInitialized
   ```

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

#### getVersion##getversion

确定当前使用的 Unity Ads SDK 版本。

1. **Objective-C**

   ```objective-c
   + (NSString *)getVersion
   ```

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

#### userIdentifier##useridentifier

为 app 的每个用户设置唯一 ID。

1. **Objective-C**

   ```objective-c
   @objc public static var userIdentifier：字符串 {...}
   ```

### 隐私##privacy

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

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

1. **Objective-C**

   ```objective-c
   + (void)setUserConsent:(BOOL)consentGranted;
   ```

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

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

1. **Objective-C**

   ```objective-c
   + (void)setUserOptOut:(BOOL)optOut;
   ```

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

启用上下文（非个性化）广告服务的显示。

1. **Objective-C**

   ```objective-c
   + (void)setNonBehavioral:(BOOL)nonBehavioral;
   ```

### UADSMetaData##uadsmetadata

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 在 [`UnityAds`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#unityads) 上使用键入的隐私方法：`setUserConsent:`、`setUserOptOut:` 和 `setNonBehavioral:`。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSMetaData` 是用于设置 GDPR 和其他隐私相关标志的上一类。

### UnityAdsInitializationDelegate##unityadsinitializationdelegate

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用带有 [`UnityAds initialize:completion:`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#unityads) 的完成代码块。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UnityAdsInitializationDelegate` 是 SDK 初始化回调的先前委托协议。

### UnityAdsLoadDelegate##unityadsloaddelegate

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用带有 [`UADSInterstitialAd load:completion:`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsinterstitialad) 或 [`UADSRewardedAd load:completion:`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsrewardedad) 的完成代码块。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UnityAdsLoadDelegate` 是以前的广告加载回调委托协议。

### UnityAdsShowDelegate##unityadsshowdelegate

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 [`UADSInterstitialShowDelegate`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsinterstitialshowdelegate) 或 [`UADSRewardedShowDelegate`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsrewardedshowdelegate)。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UnityAdsShowDelegate` 是以前的广告展示回调委托协议。

## 枚举##enum

### UADSAdFormat##uadsadformat

定义 Unity Ads 支持的不同类型的广告格式。

1. **Objective-C**

   ```objective-c
   typedef 枚举 {
     UADSAdFormatUnspecified = 0,
     UADSAdFormatInterstitial = 1,
     UADSAdFormatRewarded = 2,
     UADSAdFormatBanner = 3,
   } UADSAdFormat;
   ```

| **参数**                   | **描述**                         |
| ------------------------ | ------------------------------ |
| UADSAdFormatUnspecified  | 没有指定的广告格式。                     |
| UADSAdFormatInterstitial | 在 app 中的自然暂停时显示的全屏广告服务。        |
| UADSAdFormatRewarded     | 在完成后向用户授予奖励的广告服务。              |
| UADSAdFormatBanner       | App 布局中显示的矩形广告服务，通常锚定在屏幕顶部或底部。 |

### UnityAdsAdFormat##unityadsadformat

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 [`UADSAdFormat`](/ads-ios/4.19.0/sdk-integration/api/ios-api-objc.md#uadsadformat)。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UnityAdsAdFormat` 是广告格式类型的上一个枚举。

### UADSLogLevel##uadsloglevel

定义 Unity Ads 的日志记录级别。

1. **Objective-C**

   ```objective-c
   typedef 枚举 {
     UADSLogLevelDisabled = 0,
     UADSLogLevelError = 1,
     UADSLogLevelInfo = 2,
     UADSLogLevelDebug = 3,
   } UADSLogLevel;
   ```

| **参数**               | **描述**                                      |
| -------------------- | ------------------------------------------- |
| UADSLogLevelDisabled | 无日志输出。                                      |
| UADSLogLevelError    | 仅记录初始化/加载/显示操作中的关键错误和失败。                    |
| UADSLogLevelInfo     | 记录关键操作事件（例如初始化开始/完成、加载开始/完成、显示开始/完成以及令牌生成）。 |
| UADSLogLevelDebug    | 记录所有信息以及详细的内部操作，例如网络请求和内部错误。                |

### UADSShowFinishState##uadsshowfinishstate

表示广告展示后的完成状态。

1. **Objective-C**

   ```objective-c
   typedef 枚举 {
     UADSShowFinishStateSkipped = 0,
     UADSShowFinishStateCompleted = 1，
   } UADSShowFinishState
   ```

| **参数**                       | **描述**             |
| ---------------------------- | ------------------ |
| UADSShowFinishStateSkipped   | 用户在广告结束之前关闭或跳过了广告。 |
| UADSShowFinishStateCompleted | 广告一直播放到最后。         |

## 协议##protocol

### UADSBannerAdDelegate##uadsbanneraddelegate

1. **Objective-C**

   ```objective-c
   @protocol UADSBannerAdDelegate <NSObject>
   - (void)bannerImpression：(UADSBannerAd * _Nonnull)banner;
   - (void)bannerDidClick:(UADSBannerAd * _Nonnull)banner;
   - (void)bannerDidFailShow:(UADSBannerAd * _Nonnull)横幅报错:(id<UnityAdsError> _Nonnull)报错;
   @end
   ```

| **方法**                     | **描述**                                |
| -------------------------- | ------------------------------------- |
| `bannerImpression:`        | 显示横幅广告时调用（记录展示量）。                     |
| `bannerDidClick:`          | 用户点击横幅广告时调用。                          |
| `bannerDidFailShow:error:` | 如果横幅无法显示，则调用，并带有解释失败的`UnityAdsError`。 |

### UADSInterstitialShowDelegate##uadsinterstitialshowdelegate

1. **Objective-C**

   ```objective-c
   @protocol UADSInterstitialShowDelegate <NSObject>
   - (void)showDidStart:(UADSInterstitialAd * _Nonnull)unityAd;
   - (void)showDidClick:(UADSInterstitialAd * _Nonnull)unityAd;
   - (void)showDidComplete:(UADSInterstitialAd * _Nonnull)unityAd with:(enum UADSShowFinishState)finishState;
   - (void)showDidFail:(UADSInterstitialAd * _Nonnull)unityAd error:(id<UnityAdsError> _Nonnull)error;
   @end
   ```

| **方法**                  | **描述**                                                       |
| ----------------------- | ------------------------------------------------------------ |
| `showDidStart:`         | 在插页式广告开始显示时调用。                                               |
| `showDidClick:`         | 在点击插页式广告时调用。                                                 |
| `showDidComplete:with:` | 在广告展示完成时调用。提供`UADSShowFinishState`（`skipped` 或 `completed`）。 |
| `showDidFail:error:`    | 如果广告无法显示，则调用 ，并带有解释失败的`UnityAdsError`。                       |

### UADSRewardedShowDelegate##uadsrewardedshowdelegate

1. **Objective-C**

   ```objective-c
   @protocol UADSRewardedShowDelegate <NSObject>
   - (void)showDidStart:(UADSRewardedAd * _Nonnull)unityAd;
   - (void)showDidClick:(UADSRewardedAd * _Nonnull)unityAd;
   - (void)showDidComplete:(UADSRewardedAd * _Nonnull)unityAd with:(enum UADSShowFinishState)finishState;
   - (void)showDidFail：(UADSRewardedAd * _Nonnull)unityAd 报错：(id<UnityAdsError> _Nonnull) 报错;
   - (void)showDidReceiveReward:(UADSRewardedAd * _Nonnull)unityAd;
   @end
   ```

| **方法**                  | **描述**                                                       |
| ----------------------- | ------------------------------------------------------------ |
| `showDidStart:`         | 奖励广告开始展示时调用。                                                 |
| `showDidClick:`         | 在点击奖励广告时调用。                                                  |
| `showDidComplete:with:` | 在广告展示完成时调用。提供`UADSShowFinishState`（`skipped` 或 `completed`）。 |
| `showDidFail:error:`    | 如果广告无法显示，则调用 ，并带有解释失败的`UnityAdsError`。                       |
| `showDidReceiveReward:` | 当用户从广告中获取奖励时调用。                                              |

## UnityAdsError##unityadserror

1. **Objective-C**

   ```objective-c
   @protocol UnityAdsError
   @property（非原子、只读）NSInteger 代码；
   @property（非原子、只读、复制） NSString * _Nonnull 消息；
   @end
   ```

| **参数**  | **描述** |
| ------- | ------ |
| code    |        |
| message |        |

### UADSBannerErrorCode##uadsbannererrorcode

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 `id<UnityAdsError>` 协议。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UADSBannerErrorCode` 是横幅指定的报错代码的上一个枚举。

### UnityAdsInitializationError##unityadsinitializationerror

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 `id<UnityAdsError>` 协议。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UnityAdsInitializationError` 是初始化报错类型的上一个枚举。

### UnityAdsLoadError##unityadsloaderror

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 `id<UnityAdsError>` 协议。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UnityAdsLoadError` 是广告加载报错类型的上一个枚举。

### UnityAdsShowError##unityadsshowerror

> **Warning:**
>
> **在版本 4.19.0 中已弃用。计划在版本 5.0.0 中删除。**
>
> 请改用 `id<UnityAdsError>` 协议。请参阅 [iOS 弃用 API](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) 以了解迁移详细信息。

`UnityAdsShowError` 是广告展示报错类型的上一个枚举。