Unity Ads iOS SDK API 参考

使用 UnityAds.h 库来实现基本广告内容，例如奖励或非奖励视频、插页式或横幅广告。

#import "UnityAds.h"

本文包含以下 API 文档

类

枚举

委托

类

UnityAds

#import <UnityAds/UnityAds.h>

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

initialize

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

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

参数

描述

gameId

您项目的平台特定 Unity 游戏标识符，可在Unity Ads Monetization 仪表板上找到。

testMode

使用测试模式来测试您的集成，而不会提供实时广告。使用 true 在测试模式下初始化。

initializationDelegate

使用 UnityAdsInitializationDelegate 回调（版本 3.7.0 及更高版本）可选地启用 SDK。

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

要查询的广告单元的标识符。

Note: If you call isReady without specifying an Ad Unit ID, the method returns results for the Unity Standard Placement.

.

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 及更高版本）可选地显示内容。

Note: If you call show without specifying an Ad Unit ID, the method shows loaded content in the Unity Standard Placement. In SDK versions 4.0 and later, you must call this method with an Ad Unit 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 网络的竞标者赢得广告拍卖的情况下使用此方法。

setAdMarkup

- (void)setAdMarkup: (NSString *)adMarkup

此方法采用从竞标者服务返回的广告标记。当来自 Unity 广告网络的竞标者赢得标头出价拍卖时，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 像素乘以 50 像素。

Note: Using UADSBannerView to call a banner ad attempts to load content once, with no refreshing. If the banner returns no fill, you can destroy it and create a new one to try again. Unity recommends this method for mediated customers.

load

- (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

Note: This delegate is deprecated and will be removed in a future major version release of the 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

当横幅加载并准备好放置在视图层次结构中时调用。

unityAdsRefreshBannerDidNoFill

当横幅没有可用的广告内容时调用。

unityAdsRefreshBannerDidShow

当横幅对用户可见时调用。

unityAdsRefreshBannerDidHide

当横幅对用户隐藏时调用。

unityAdsRefreshBannerDidClick

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

unityAdsRefreshBannerDidError

当 UnityAdsBanner 遇到错误时调用。

参数

描述

message

与错误相关的消息。

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.