Unity Ads iOS SDK API 参考

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

阅读时间11 分钟

最后更新于 5 个月前

使用

UnityAds.h

库可以实现基本广告内容，例如奖励或非奖励视频广告、插页式广告或横幅广告。


#import "UnityAds.h"

本文包含以下 API 文档：类

```
UnityAds
```
```
UADSLoadOptions
```
```
UADSBannerView
```

枚举

```
UnityAdsBannerPosition
```
```
UnityAdsInitializationError
```
```
UnityAdsLoadError
```
```
UnityAdsShowError
```
```
UnityAdsError
```

委托

```
UnityAdsInitializationDelegate
```
```
UnityAdsLoadDelegate
```
```
UnityAdsShowDelegate
```
```
UADSBannerDelegate
```
```
UADSBannerAdRefreshViewDelegate
```

类

UnityAds


#import <UnityAds/UnityAds.h>

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

initialize


+ (void) initialize: (NSString *)gameId    testMode(BOOL)testMode    initializationDelegate: (nullable id<UnityAdsInitializationDelegate>)initializationDelegate;}

使用指定的 Game ID（游戏 ID）、测试模式状态和初始化委托来初始化广告服务。

参数	描述
`gameId`	Unity Ads Monetization（变现）后台中项目的特定于平台的 Unity 游戏标识符。
`testMode`	使用测试模式可以在不投放真实广告的情况下测试集成情况。使用 `true` 在测试模式下进行初始化。
`initializationDelegate`	（可选）使用 `UnityAdsInitializationDelegate` 回调启用 SDK（3.7.0 和更高版本）。

load


+ (void)load: (NSString *)placementId options: (UADSLoadOptions *)options loadDelegate: (nullable id<UnityAdsLoadDelegate>)loadDelegate {  [UADSLoadModule.sharedInstance loadForPlacementID: placementId	      						    options: options    						         loadDelegate: loadDelegate];}

加载指定广告单元的广告内容。必须在调用

show

之前先调用

load

。

参数	描述
`placementId`	要加载广告内容的广告单元的标识符。
`options`	一组用于修改广告加载行为的选项。
`loadDelegate`	（可选）使用 `UnityAdsLoadDelegate` 回调加载广告内容（3.7.0 和更高版本）。

isReady

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。


+ (BOOL)isReady: (NSString *)adUnitId {  return [UnityServices isSupported] && [UnityServices isInitialized] && [UADSPlacement isReady: adUnitId];}

如果指定的广告单元已准备好展示广告，返回

YES

。如果在启用

enablePerPlacementLoad

的情况下初始化了 SDK，则必须在调用

show

之前先调用

load

。

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

注意

如果在未指定广告单元 ID 的情况下调用

isReady

，则该方法会返回 Unity 标准广告位的结果。

show


+ (void)show: (UIViewController *)viewController placementId: (NSString *)placementId showDelegate: (nullable id<UnityAdsShowDelegate>)showDelegate { 	[self show: viewController       adUnitId: placementId        options: [UADSShowOptions new]   showDelegate: showDelegate];}

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

参数	描述
`placementId`	要展示的广告单元的标识符。
`options`	一组用于修改广告展示行为的选项。
`showDelegate`	（可选）使用 `UnityAdsShowDelegate` 回调展示广告内容（3.7.0 和更高版本）。

注意

如果在未指定广告单元 ID 的情况下调用

show

，则该方法会展示 Unity 标准广告位中加载的内容。在 SDK 4.0 及更高版本中，必须使用广告单元 ID 调用此方法。

addDelegate

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。


+ (void)addDelegate: (__nullable id<UnityAdsDelegate>)delegate {  [UADSProperties addDelegate: delegate];}

添加一个用于接收 Unity Ads 回调的监听器委托。在 3.1.0 及更高版本中，您可以注册多个监听器。这对于聚合客户特别有用。

参数	描述
`delegate`	用于 Unity Ads 回调的监听器。

removeDelegate

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。


+ (void)removeDelegate: (id<UnityAdsDelegate>)delegate {    [UADSProperties removeDelegate: delegate];}

移除活动的

UnityAdsDelegate

监听器。

参数	描述
`delegate`	用于 Unity Ads 回调的监听器。

setDebugMode


+ (BOOL)getDebugMode {  return [UnityServices getDebugMode];}

控制 SDK 的日志输出量。设置为

YES

可获得更详细完整的日志记录。

getDebugMode


+ (void)getDebugMode: (BOOL)enableDebugMode {  [UnityServices setDebugMode: enableDebugMode];}

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

YES

，否则返回

NO

。

getVersion


+ (NSString *)getVersion {  return [UnityServices getVersion];}

返回 Unity Ads SDK 的当前版本。

isInitialized


+ (BOOL)isInitialized {  return [USRVSdkProperties isInitialized];}

如果 SDK 已成功初始化，返回

YES

，否则返回

NO

。

UADSLoadOptions


#import <UnityAds/UADSBaseOptions.h>@interface UADSLoadOptions : UADSBaseOptions@property (nonatomic, readwrite) NSString *adMarkup;@end

此类包含要使用

load

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

setAdMarkup


- (void)setAdMarkup: (NSString *)adMarkup

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

UADSBannerView


@interface UADSBannerView : UIView

使用此类可实现横幅广告。Unity Ads 3.3 及更高版本通过单个广告单元支持多个横幅广告实例。

initWithPlacementId


-(instancetype)initWithPlacementId:(NSString *)placementId size:(CGSize)size;

使用广告单元 ID 和横幅大小实现横幅广告视图。调用

initWithPlacementId

以初始化对象，然后调用

load

以加载广告内容。请注意，横幅对象通过其

UADSBannerViewDelegate

监听器访问生命周期事件。

参数	描述
`placementId`	横幅广告单元 ID。
`size`	横幅对象的 `size` 。支持的最小大小为 320 像素 x 50 像素。

注意

使用

UADSBannerView

调用横幅广告会尝试加载一次内容，不会刷新。如果横幅返回无填充内容，则可以将其销毁并创建一个新的以重试。Unity 为聚合客户推荐此方法。


- (void)load;

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

枚举

UnityAdsPlacementState

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。


typedef NS_ENUM(NSInteger, UnityAdsPlacementState)

广告单元的状态枚举。

值	描述
`kUnityAdsPlacementStateReady`	广告单元已准备好展示广告。
`kUnityAdsPlacementStateNotAvailable`	广告单元不可用。
`kUnityAdsPlacementStateDisabled`	已禁用广告单元。
`kUnityAdsPlacementStateWaiting`	广告单元正在等待准备就绪。
`kUnityAdsPlacementStateNoFill`	广告单元没有可展示的广告。

UnityAdsFinishState

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。


typedef NS_ENUM(NSInteger, UnityAdsFinishState)

用户与广告互动的状态枚举。广告播放完成时，SDK 会将此值传递给

unityAdsDidFinish

回调方法。

值	描述
`kUnityAdsFinishStateError`	表示由于 Unity 错误而未能播放完广告。
`kUnityAdsFinishStateSkipped`	表示用户跳过了广告。
`kUnityAdsFinishStateCompleted`	表示广告已完成播放。

UnityAdsInitializationError


typedef NS_ENUM (NSInteger, UnityAdsInitializationError)

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

值	描述
`kUnityInitializationErrorInternalError`	由于环境或内部服务而发生错误。
`kUnityInitializationErrorInvalidArgument`	由于 Initialize 方法中的参数无效而发生错误。
`kUnityInitializationErrorAdBlockerDetected`	由于 URL 被阻止而发生错误。

UnityAdsLoadError


typedef NS_ENUM (NSInteger, UnityAdsLoadError)

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

值	描述
`kUnityAdsLoadErrorInitializeFailed`	由于 SDK 未初始化而导致广告加载失败。
`kUnityAdsLoadErrorInternal`	由于内部 Unity Ads 服务错误而导致广告加载失败。
`kUnityAdsLoadErrorInvalidArgument`	由于 `load` 方法中的参数无效而导致广告加载失败。
`kUnityAdsLoadErrorNoFill`	由于广告平台上没有可用的内容而导致广告加载失败。
`kUnityAdsLoadErrorTimeout`	广告未能在指定的时间范围内加载。

UnityAdsShowCompletionState


typedef NS_ENUM (NSInteger, UnityAdsShowCompletionState)

广告已结束的原因枚举。

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

UnityAdsShowError


typedef NS_ENUM (NSInteger, UnityAdsShowError)

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

值	描述
`kUnityShowErrorNotInitialized`	由于 SDK 未初始化而导致广告展示失败。
`kUnityShowErrorNotReady`	由于广告单元尚未准备就绪而导致广告展示失败。
`kUnityShowErrorVideoPlayerError`	由于媒体播放器错误而导致广告展示失败。
`kUnityShowErrorInvalidArgument`	由于 `show` 方法中的参数无效而导致广告展示失败。
`kUnityShowErrorNoConnection`	由于互联网连接错误而导致广告展示失败。
`kUnityShowErrorAlreadyShowing`	由于广告已在展示而导致广告展示失败。
`kUnityShowErrorInternalError`	由于内部 Unity Ads 服务错误而导致广告展示失败。

UnityAdsError

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。


typedef NS_ENUM (NSInteger, UnityAdsError)

通过

unityAdsDidError

回调发出的 Unity Ads 错误的原因枚举。

值	描述
`kUnityAdsErrorNotInitialized = 0`	Unity Ads 服务当前未初始化。
`kUnityAdsErrorInitializedFailed`	初始化过程中发生错误。
`kUnityAdsErrorInvalidArgument`	由于参数无效，Unity Ads 初始化失败。
`kUnityAdsErrorVideoPlayerError`	由于视频播放器失败而发生错误。
`kUnityAdsErrorInitSanityCheckFail`	由于环境无效而导致 Unity Ads 服务初始化失败。
`kUnityAdsErrorAdBlockerDetected`	由于广告拦截而产生的错误。
`kUnityAdsErrorFileIoError`	由于无法读取或写入文件而发生错误。
`kUnityAdsErrorDeviceIdError`	由于设备标识符错误而产生的错误。
`kUnityAdsErrorShowError`	尝试展示广告时出错。
`kUnityAdsErrorInternalError`	Unity Ads 内部服务错误。

UnityAdsBannerPosition

可设置为横幅广告锚点的位置枚举。

值	描述
`kUnityAdsBannerPositionTopLeft`	将横幅广告锚定在屏幕的左上角。
`kUnityAdsBannerPositionTopCenter`	将横幅广告锚定在屏幕的顶部中央位置。
`kUnityAdsBannerPositionTopRight`	将横幅广告锚定在屏幕的右上角。
`kUnityAdsBannerPositionBottomLeft`	将横幅广告锚定在屏幕的左下角。
`kUnityAdsBannerPositionBottomCenter`	将横幅广告锚定在屏幕的底部中央位置。
`kUnityAdsBannerPositionBottomRight`	将横幅广告锚定在屏幕的右下角。
`kUnityAdsBannerPositionCenter`	将横幅广告锚定在屏幕的中央位置。
`kUnityAdsBannerPositionNone`	不锚定横幅广告。

委托

UnityAdsInitializationDelegate


@protocol UnityAdsInitializationDelegate <NSObject>- (void)initializationComplete;- (void)initializationFailed: (UnityAdsInitializationError)error withMessage: (NSString *)message;@end

实现此委托可以处理

initialize

结果。

initializationComplete

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

initializationFailed

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

参数	描述
`error`	导致初始化失败的 `UnityAdsInitializationError` 。
`message`	与错误相关的消息。

UnityAdsLoadDelegate


@protocol UnityAdsLoadDelegate <NSObject>- (void)unityAdsAdLoaded: (NSString *)placementId;- (void)unityAdsAdFailedToLoad: (NSString *)placementId       withError: (UnityAdsLoadError)error     withMessage: (NSString *)message;@end

实现此委托可以处理

load

结果。

unityAdsAdLoaded

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

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

unityAdsAdFailedToLoad

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

参数	描述
`placementId`	内容加载失败的广告单元的标识符。
`error`	导致加载失败的 UnityAdsLoadError。
`message`	与错误相关的消息。

UnityAdsShowDelegate


@protocol UnityAdsShowDelegate <NSObject>- (void)unityAdsShowComplete: (NSString *)adUnitId withFinishState: (UnityAdsShowCompletionState)state;- (void)unityAdsShowFailed: (NSString *)adUnitId withError: (UnityAdsShowError)error withMessage: (NSString *)message;- (void)unityAdsShowStart: (NSString *)adUnitId;- (void)unityAdsShowClick: (NSString *)adUnitId;@end

实现此委托可以处理

show

结果。

unityAdsShowComplete

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

参数	描述
`adUnitId`	展示内容的广告单元的标识符。
`state`	表示广告已跳过或完成。

unityAdsShowStart

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

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

unityAdsShowClick

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

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

unityAdsShowFailed

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

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

UnityAdsDelegate

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。


@protocol UnityAdsDelegate <NSObject>- (void)unityAdsReady: (NSString *)placementId;- (void)unityAdsDidError: (UnityAdsError)error withMessage: (NSString *)message;- (void)unityAdsDidStart: (NSString *)placementId;- (void)unityAdsDidFinish: (NSString *)placementId   withFinishState: (UnityAdsFinishState)state;@end

实现此委托可以处理广告的各种状态。在脚本中实现此委托可以定义奖励广告的逻辑。

unityAdsReady

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。

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

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

unityAdsDidError

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。

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

参数	描述
`error`	导致错误的 `UnityAdsError` 。
`message`	与错误相关的消息。

unityAdsDidStart

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。

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

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

unityAdsDidFinish

重要

已在 SDK 4.0 版本中移除。如需了解更多信息，请参阅已弃用的 API 类。

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

参数	描述
`placementId`	完成广告展示的广告单元的标识符。
`state`	广告展示的结果用户事件。

UADSBannerDelegate


@protocol UADSBannerViewDelegate <NSObject> @optional- (void)bannerViewDidLoad: (UADSBannerView *)bannerView;- (void)bannerViewDidClick: (UADSBannerView *)bannerView;- (void)bannerViewDidLeaveApplication: (UADSBannerView *)bannerView;- (void)bannerViewDidError: (UADSBannerView *)bannerView error: (UADSBannerError *)error;@end

此委托提供来自 Unity Ads 横幅广告事件的回调。

bannerViewDidLoad

横幅成功加载广告内容时触发此回调。

bannerViewDidClick

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

bannerViewDidLeaveApplication

由于用户退出应用程序而导致横幅广告关闭时触发此回调。

bannerViewDidError

UnityAdsBanner 遇到错误时触发此回调。

参数	描述
`error`	导致错误的 `UADSBannerError` 。

UADSBannerAdRefreshViewDelegate

注意

此委托已被弃用，并将从 Unity Ads SDK 未来发布的主要版本中移除。


@protocol UADSBannerAdRefreshViewDelegate <NSObject> @optional- (void)unityAdsRefreshBannerDidLoad: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidNoFill: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidShow: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidHide: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidClick: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidError: (UADSBannerAdRefreshView *)bannerAdRefreshView message: (NSString *)message;@end

此委托提供来自 Unity Ads 刷新横幅广告事件的回调。

unityAdsRefreshBannerDidLoad

当横幅广告已加载并准备好放置在 View 层级视图中时调用。

unityAdsRefreshBannerDidNoFill

当横幅中无可用的广告内容时调用。

unityAdsRefreshBannerDidShow

横幅广告对用户可见时调用。

unityAdsRefreshBannerDidHide

横幅广告对用户隐藏时调用。

unityAdsRefreshBannerDidClick

用户点击了横幅广告时调用。

unityAdsRefreshBannerDidError

当

UnityAdsBanner

遇到错误时调用。

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

Unity Ads iOS SDK API 参考

类

UnityAds

initialize

参数

描述

load

参数

描述

isReady

参数

描述

show

参数

描述

addDelegate

参数

描述

removeDelegate

参数

描述

setDebugMode

getDebugMode

getVersion

isInitialized

UADSLoadOptions

setAdMarkup

UADSBannerView

initWithPlacementId

参数

描述

load

枚举

UnityAdsPlacementState

值

描述

UnityAdsFinishState

值

描述

UnityAdsInitializationError

值

描述

UnityAdsLoadError

值

描述

UnityAdsShowCompletionState

值

描述

UnityAdsShowError

值

描述

UnityAdsError

值

描述

UnityAdsBannerPosition

值

描述

委托

UnityAdsInitializationDelegate

initializationComplete

initializationFailed

参数

描述

UnityAdsLoadDelegate

unityAdsAdLoaded

参数

描述

unityAdsAdFailedToLoad

参数

描述

UnityAdsShowDelegate

unityAdsShowComplete

参数

描述

unityAdsShowStart

参数

描述

unityAdsShowClick

参数

描述