Unity Ads Android SDK API 参考 - Kotlin 和 Java
通过访问 Unity Ads SDK 公共 API 参考,可以查看在 Kotlin 和 Java 中可用于集成和控制 Android 应用程序广告行为的类、方法和属性。
阅读时间42 分钟最后更新于 18 天前
在将 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