Unity Ads Android SDK API 参考 - Kotlin 和 Java
通过访问 Unity Ads SDK 公共 API 参考,可以查看在 Kotlin 和 Java 中可用于集成和控制 Android 应用程序广告行为的类、方法和属性。
阅读时间42 分钟最后更新于 2 个月前
在将 Unity Ads 集成到 Android 应用程序时,请使用此 Unity Ads Android SDK API 参考。
在使用此 API 之前,请确保已导入 库以在您的应用程序中启用变现功能。有关更多信息,请参阅 导入 UnityAds 库。
UnityAds类
BannerAd
BannerAdBannerLoadConfiguration
封装加载 所需的选项。
BannerAd参数 | 描述 | 必需 |
|---|---|---|
| 横幅广告位的唯一标识符。 | 是 |
| 广告的 | 是 |
| 竞价场景的广告标记。 | 否 |
| 聚合合作伙伴信息。 | 否 |
| 由聚合用于跟踪效果。 | 否 |
| 附加键值参数的映射。 | 否 |
| 用于处理横幅广告生命周期事件的 BannerShowListener。 | 否 |
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()
BannerLoadConfiguration.Builder
用于创建 实例的构建器类。
BannerLoadConfiguration构造函数
Builder(placementId:String, bannerSize:BannerSize)
参数 | 描述 | 必需 |
|---|---|---|
| 横幅广告位的唯一标识符。 | 是 |
| 广告的 | 是 |
返回:一个新的 实例。
BannerLoadConfiguration.Builder构建器方法
方法 | 参数 | 必需 | 返回 | 描述 |
|---|---|---|---|---|
| | | | 设置广告标记并返回构建器以进行链式调用。 |
| | | | 设置聚合信息并返回构建器以进行链式调用。 |
| | | | 设置聚合广告单元 ID 并返回构建器以进行链式调用。 |
| | | | 设置 extras 映射并返回构建器以进行链式调用。 |
| | | | 设置显示监听器并返回构建器以进行链式调用。 |
| None | | | 创建并返回带有已配置参数的 |
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()
load()
使用指定的 BannerLoadConfiguration 加载横幅广告。
参数 | 描述 | 必需 |
|---|---|---|
| 包含横幅特定加载选项的 | 是 |
| 一个 | 是 |
返回: (void) - 这是一个异步方法,会立即返回。结果通过 回调提供。
UnitBannerLoadListenerval bannerSize = BannerSize(320, 50)val loadConfig = BannerLoadConfiguration.Builder(\"banner_placement\", bannerSize).build()BannerAd.load(loadConfig, { bannerAd, error -> if (bannerAd != null) { // 横幅加载成功,您现在可以将其添加到视图层级中 this.bannerAd = bannerAd } else { // 处理加载错误 }})
view
提供对横幅广告实例访问权限的视图属性。使用此属性可将横幅广告插入到您应用现有视图层级中的所需位置。
返回: (可为空的 View) - 包含横幅广告的 Android View,如果广告未成功加载,则返回 null。
View?// 假设 'bannerAd' 是已加载的 BannerAd 实例// 假设 'adPlaceholder' 是布局中您想要显示广告的 ViewGroup(例如 LinearLayout、FrameLayout)bannerAd.view?.let { adPlaceholder.addView(it)}
BannerView
BannerViewBannerView.IListener
BannerView.IListenerBannerSize
表示横幅广告尺寸的数据类。
参数 | 描述 | 必需 |
|---|---|---|
| 横幅广告的宽度(以像素为单位)。 | 是 |
| 横幅广告的高度(以像素为单位)。 | 是 |
val bannerSize = BannerSize(320, 50)
UnityBannerSize
UnityBannerSizeInitializationConfiguration
一个包含 SDK 初始化所有设置的类。此类的实例是使用其 创建的。
Builder参数 | 描述 | 必需 |
|---|---|---|
| 您在 Unity Ads 变现控制面板中的唯一游戏标识符。 | 是 |
| 一个启用测试模式的布尔值。当为 true 时,仅显示测试广告。默认为 false。 | 否 |
| 指定日志输出的详细程度。请参阅 | 否 |
| 包含有关聚合合作伙伴的信息的对象。请参阅 | 否 |
| 用于高级配置的附加键值参数映射。 | 否 |
InitializationConfiguration.Builder
用于创建 实例的构建器类。
InitializationConfiguration构造函数
Builder(gameId:String)
参数 | 描述 | 必需 |
|---|---|---|
| 您在 Unity Ads 变现控制面板中的唯一游戏标识符。 | 是 |
返回:一个新的 实例。
InitializationConfiguration.Builder构建器方法
方法 | 参数 | 必需 | 返回 | 描述 |
|---|---|---|---|---|
| | | | 设置测试模式并返回构建器以进行链式调用。 |
| | | | 设置日志级别并返回构建器以进行链式调用。 |
| | | | 设置聚合信息并返回构建器以进行链式调用。 |
| | | | 设置附加参数映射并返回构建器以进行链式调用。 |
| None | | | 创建并返回带有已配置参数的 |
val config = InitializationConfiguration.Builder(\"YOUR_GAME_ID\") .withTestMode(true) .withLogLevel(LogLevel.DEBUG) .withMediationInfo(mediationInfo) .withExtras(mapOf(\"key\" to \"value\")) .build()
initialize()
使用指定的配置初始化 Unity Ads SDK。当初始化成功或失败完成时,将调用 。
InitializationListener参数 | 描述 | 必需 |
|---|---|---|
| 包含初始化 SDK 所需设置的 | 否 |
| 完成时将调用 | 否 |
返回: (void) - 这是一个异步方法,会立即返回。结果通过 回调提供。
UnitInitializationListener@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)}
InterstitialAd
InterstitialAdload()
使用指定的 LoadConfiguration 加载插页式广告。
参数 | 描述 | 必需 |
|---|---|---|
| 包含广告加载选项的 | 否 |
| 加载完成时调用的 | 否 |
InterstitialAd.load(loadConfig, { interstitialAd, error -> if (interstitialAd != null) { // 广告加载成功,准备展示 this.interstitialAd = interstitialAd } else { // 处理加载错误 }})
show()
显示之前加载的插页式广告。
参数 | 描述 | 必需 |
|---|---|---|
| 包含广告展示选项的 | 否 |
| 用于处理广告生命周期事件的可选 | 否 |
返回: (void) - 此方法在启动广告展示流程后立即返回。生命周期事件通过 回调提供。
UnitShowListenerinterstitialAd.show(showConfig, interstitialShowListener)
LoadConfiguration
封装用于加载 和 格式的选项。
InterstitialAdRewardedAd参数 | 描述 | 必需 |
|---|---|---|
| 您的广告位的唯一标识符,可在 Unity 变现控制面板上找到。 | 是 |
| 竞价场景的广告标记。 | 否 |
| 聚合合作伙伴信息。 | 否 |
| 由聚合用于跟踪效果。 | 否 |
| 附加键值参数的映射。 | 否 |
val loadConfiguration = LoadConfiguration.Builder(\"interstitial_placement\") .withAdMarkup("ad_markup") .withMediationInfo(mediationInfo) .withMediationAdUnitId("mediation_ad_unit_id") .withExtras(mapOf(\"key\" to \"value\")) // 多次调用此方法将覆盖之前的值。 .build()
LoadConfiguration.Builder
用于创建 实例的构建器类。
LoadConfiguration构造函数
Builder(placementId:字符串)
参数 | 描述 | 必需 |
|---|---|---|
| 您的广告位的唯一标识符,可在 Unity 变现控制面板上找到。 | 是 |
返回:一个新的 实例。
LoadConfiguration.Builder构建器方法
方法 | 参数 | 必需 | 返回 | 描述 |
|---|---|---|---|---|
| | 否 | | 设置广告标记并返回构建器以进行链式调用。 |
| | 否 | | 设置聚合信息并返回构建器以进行链式调用。 |
| | 否 | | 设置聚合广告单元 ID 并返回构建器以进行链式调用。 |
| | 否 | | 设置 extras 映射并返回构建器以进行链式调用。 |
| None | 否 | | 创建并返回配置了参数的 |
UnityAdsLoadOptions
UnityAdsLoadOptionsMediationInfo
一个包含所用聚合合作伙伴相关信息的类。
参数 | 描述 | 必需 |
|---|---|---|
| 聚合合作伙伴的名称。 | 是 |
| 聚合合作伙伴 SDK 的版本。 | 是 |
| 聚合合作伙伴的 Unity Ads 适配器版本。 | 是 |
val mediationInfo = MediationInfo("partner_name", "1.2.3", "4.5.6")
MediationMetaData
MediationMetaDataRewardedAd
RewardedAdload()
使用指定的 加载激励广告。
LoadConfiguration参数 | 描述 | 必需 |
|---|---|---|
| 包含广告加载选项的 | 是 |
| 一个 | 是 |
RewardedAd.load(loadConfig, { rewardedAd, error -> if (rewardedAd != null) { // 广告加载成功,准备展示 this.rewardedAd = rewardedAd } else { // 处理加载错误 }})
show()
显示先前加载的激励广告。
参数 | 描述 | 必需 |
|---|---|---|
| 包含广告展示选项的 | 是 |
| 一个可选的 | 是 |
返回: (void) - 此方法在启动广告展示流程后立即返回。生命周期事件通过 回调提供。
UnitShowListenerrewardAd.show(showConfig, rewardedAdShowListener)
ShowConfiguration
封装用于显示 和 格式的附加选项。
InterstitialAdRewardedAd参数 | 描述 | 必需 |
|---|---|---|
| 用于跟踪完成情况。 | 否 |
| 在显示广告时传递的附加键值参数映射。 | 否 |
val showConfiguration = ShowConfiguration.Builder().withCustomRewardString("custom_reward_string").withExtras(mapOf(\"key\" to \"value\")).build()
ShowConfiguration.Builder
用于创建 实例的构建器类。
ShowConfiguration构造函数
构建器()
返回:一个新的 实例。
ShowConfiguration.Builder构建器方法
方法 | 参数 | 必需 | 返回 | 描述 |
|---|---|---|---|---|
| | | | 设置自定义奖励字符串并返回构建器以进行链式调用。 |
| | | | 设置额外参数映射并返回构建器以进行链式调用。 |
| None | | | 创建并返回带有已配置参数的 |
UnityAdsShowOptions
UnityAdsShowOptionsTokenConfiguration
一个包含生成竞价令牌设置的类。
参数 | 描述 | 必需 |
|---|---|---|
| 用于生成令牌的广告格式(例如 | 是 |
| 一个包含有关聚合合作伙伴信息的对象。请参阅 | 否 |
| 一个包含额外键值参数的映射。 | 否 |
val tokenConfig = TokenConfiguration.Builder(AdFormat.REWARDED) .withMediationInfo(mediationInfo) .withExtras(extras) .build()
TokenConfiguration.Builder
用于创建 实例的构建器类。
TokenConfiguration构造函数
Builder(adFormat:AdFormat)
参数 | 描述 | 必需 |
|---|---|---|
| 用于生成令牌的 AdFormat(例如 | 是 |
返回:一个新的 实例。
TokenConfiguration.Builder构建器方法
方法 | 参数 | 必需 | 返回 | 描述 |
|---|---|---|---|---|
| | | | 设置聚合信息并返回构建器以进行链式调用。 |
| | | | 设置额外映射并返回构建器以进行链式调用。 |
| None | | | 创建并返回带有已配置参数的 |
getToken
根据提供的 获取竞价令牌,并将其传递给令牌监听器。
TokenConfiguration参数 | 描述 | 必需 |
|---|---|---|
| 一个 | 是 |
| 一个监听器,在令牌成功获取时调用并传入该令牌;如果发生错误,则返回 null。 | 是 |
返回: (void) - 这是一个立即返回的异步方法。结果通过 回调提供。
UnitTokenListenerUnityAds.getToken(tokenConfig, listener)
UnityAds
UnityAds 类是一个静态类,作为 SDK 的主要入口点。它处理初始化、令牌检索,并提供对全局 SDK 属性的访问。
静态变量
isInitialized
一个用于确定 Unity Ads SDK 是否已成功初始化的布尔属性。
返回:如果 Unity Ads SDK 已成功初始化,则为 true。
val isInitialized = UnityAds.isInitialized
version
一个返回当前 Unity Ads SDK 版本的字符串属性。
返回:当前安装的 Unity Ads SDK 版本。
val sdkVersion = UnityAds.version
userIdentifier
一个表示您应用中每个用户唯一 ID 的字符串属性。
返回:当前值。
UnityAds.userIdentifier = "my-user-id"
隐私
使用以下方法设置隐私和用户同意标志,以帮助您遵守受支持的隐私法规。
setUserConsent()
显示用户针对个性化广告的选择。
setUserOptOut()
为用户提供选择退出数据收集和个性化广告的选项。
setNonBehavioral()
启用情境(非个性化)广告的展示。
UnityAds.userConsent = trueUnityAds.userOptOut = falseUnityAds.nonBehavioral = false
MetaData
MetaDataUnityAdsError
class UnityAdsError internal constructor( val code:整型, val message:字符串)
Unity Ads 在出现错误时返回的异常。
参数 | 描述 |
|---|---|
| 与错误相关的消息。 |
| 错误代码。 |
BannerErrorCode
BannerErrorCodeBannerErrorInfo
BannerErrorInfoUnityAds.UnityAdsInitializationError
UnityAds.UnityAdsInitializationErrorUnityAds.UnityAdsLoadError
UnityAds.UnityAdsLoadErrorUnityAds.UnityAdsShowError
UnityAds.UnityAdsShowError接口
BannerLoadListener
用于处理 加载结果的接口。当横幅广告加载请求完成时,将调用此监听器,并提供成功加载的 实例或错误。
BannerAdBannerAd方法签名
fun interface BannerLoadListener { fun onBannerLoaded(bannerAd:BannerAd?, error:UnityAdsError?)}
方法 | 参数 | 描述 |
|---|---|---|
| | 在横幅广告加载请求完成时调用。正好只有一个参数不为 null。 |
val bannerLoadListener = BannerLoadListener { bannerAd, error -> if (bannerAd != null) { // 横幅已成功加载 this.bannerAd = bannerAd // 将 banner.view 添加到您的视图层级中 } else { // 处理加载错误 Log.e(\"UnityAds\", \"Banner load failed: ${error?.message}\") }}
BannerShowListener
用于处理 显示生命周期事件的接口。此监听器在横幅广告显示生命周期的各个阶段被调用。
BannerAd方法签名
interface BannerShowListener { fun onBannerShown(bannerAd:BannerAd) fun onBannerClicked(bannerAd:BannerAd) fun onBannerFailedToShow(bannerAd:BannerAd, error:UnityAdsError)}
方法 | 参数 | 描述 |
|---|---|---|
| | 横幅广告成功显示在屏幕上时调用。 |
| | 用户点击横幅广告时调用。 |
| | 横幅广告显示失败时调用。 |
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}\") }}
InitializationListener
用于接收有关 SDK 初始化状态回调的接口。当 SDK 初始化过程完成时,将调用此监听器。
方法签名
fun interface InitializationListener { fun onInitializationComplete(error:UnityAdsError?)}
方法 | 参数 | 描述 |
|---|---|---|
| | 当 SDK 初始化完成时调用。如果 error 为 null,则表示初始化成功。 |
val listener = InitializationListener { error -> if (error == null) { Log.d(\"UnityAds\", \"SDK initialized successfully.\") } else { Log.e("UnityAds", "SDK 初始化失败: ${error.message}") }}
IUnityAdsInitializationListener
IUnityAdsInitializationListenerInterstitialLoadListener
用于处理 加载结果的接口。当插屏广告加载请求完成时,将调用此监听器,并提供成功加载的 实例或错误信息。
InterstitialAdInterstitialAd方法签名
fun interface InterstitialLoadListener { fun onInterstitialLoaded(interstitialAd:InterstitialAd?, error:UnityAdsError?)}
方法 | 参数 | 描述 |
|---|---|---|
| | 当插屏广告加载请求完成时调用。参数中恰好有一个将为非空值。 |
val interstitialLoadListener = InterstitialLoadListener { interstitialAd, error -> if (interstitialAd != null) { // 插屏广告加载成功 this.interstitialAd = interstitialAd // 您现在可以展示广告了 } else { // 处理加载错误 Log.e("UnityAds", "插屏加载失败: ${error?.message}") }}
RewardedLoadListener
用于处理 加载结果的接口。当激励广告加载请求完成时,将调用此监听器,并提供成功加载的 实例或错误。
RewardedAdRewardedAd方法签名
fun interface RewardedLoadListener { fun onRewardedLoaded(rewardedAd:RewardedAd?, error:UnityAdsError?)}
方法 | 参数 | 描述 |
|---|---|---|
| | 当激励广告加载请求完成时调用。参数中恰好有一个不为 null。 |
val rewardedLoadListener = RewardedLoadListener { rewardedAd, error -> if (rewardedAd != null) { // 激励广告加载成功 this.rewardedAd = rewardedAd // 您现在可以展示广告 } else { // 处理加载错误 Log.e(\"UnityAds\", \"激励广告加载失败:${error?.message}\") }}
IUnityAdsLoadListener
IUnityAdsLoadListenerShowListener
用于处理 或 展示生命周期事件的接口。此通用接口为广告展示生命周期的各个阶段提供回调。
ShowAdRewardedAd方法签名
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 callbackinterface RewardedShowListener:ShowListener<RewardedAd> { fun onRewarded(unityAd:RewardedAd)}
方法 | 参数 | 描述 |
|---|---|---|
| | 当广告开始在屏幕上显示时调用。 |
| | 当用户点击广告时调用。 |
| | 当广告结束显示时调用。对于激励广告, |
| | 当广告未能显示时调用。 |
| | 当用户通过观看激励广告至结束而获得奖励时调用。 |
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 }}
IUnityAdsShowListener
IUnityAdsShowListenerTokenListener
用于接收 调用结果的接口。当竞价令牌请求完成时,将调用此监听器。
getToken方法签名
fun interface TokenListener { fun onTokenReady(token:String?)}
方法 | 参数 | 描述 |
|---|---|---|
| | 在令牌请求完成时调用。应将该令牌传递给您的中介合作伙伴的 SDK 以进行竞价。 |
val listener = TokenListener { token -> if (token != null) { // 将令牌传递给您的中介合作伙伴的 SDK Log.d(\"UnityAds\", \"Token received: $token\") } else { // 处理令牌检索失败 Log.e(\"UnityAds\", \"Token retrieval failed\") }}
onAdExpired
InterstitialAdRewardedAd方法签名
// On InterstitialAdvar onAdExpired:AdExpiredListener?// On RewardedAdvar onAdExpired:AdExpiredListener?fun interface AdExpiredListener { fun onAdExpired(ad:T) // T 是 InterstitialAd 或 RewardedAd}
参数 | 描述 |
|---|---|
| (必需) 一个在广告过期时接收过期广告实例的函数。 |
返回: (void) - 此方法注册回调并立即返回。
Unit// 对于 InterstitialAdinterstitialAd.onAdExpired = AdExpiredListener { ad -> // 处理广告过期 - 加载新广告 Log.d("UnityAds", "插屏广告过期") // 加载新广告}// For RewardedAdrewardedAd.onAdExpired = AdExpiredListener { ad -> // Handle ad expiration - load a new ad Log.d("UnityAds", "激励广告过期") // Load a new ad}
枚举
AdFormat
不同广告格式的枚举类型。
值 | 描述 |
|---|---|
| 在应用自然中断时显示的全屏广告,几秒钟后可跳过。 |
| 用户选择观看以换取应用内奖励的全屏广告。 |
| 占据屏幕一部分的广告,通常位于顶部或底部。 |
LogLevel
不同日志详细程度的枚举类型。
值 | 描述 |
|---|---|
| 不应打印与 Unity Ads 相关的日志。 |
| 默认级别。显示标准集成和Lifecycle消息。 |
| 显示用于调试的详细日志。 |
| 来自初始化/加载/展示操作的基本错误,以及开发者必须注意的关键故障。 |
ShowFinishState
描述广告展示后最终状态的枚举类型。
值 | 描述 |
|---|---|
| 用户在广告播放结束前跳过了广告。 |
| 广告已完整播放。对于 |
UnityAds.UnityAdsShowCompletionState
UnityAds.UnityAdsShowCompletionState