Unity Ads Android SDK API 参考

本文包含以下 API 文档：

类

枚举

接口

类

UnityAds

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

initialize

initialize(final Context context, final String gameId, final boolean testMode, final IUnityAdsInitializationListener initializationListener)

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

参数

描述

context

当前 Android Context。

gameId

Monetization（变现）后台中项目的特定于平台的 Unity 游戏标识符。

testMode

使用测试模式可以在不投放真实广告的情况下测试集成情况。使用 true 在测试模式下进行初始化。

initializationListener

（可选）使用 IUnityAdsInitializationListener 回调启用 SDK（3.7.0 和更高版本）。

load

public static void load(final String adUnitId, final UnityAdsLoadOptions loadOptions, final IUnityAdsLoadListener listener)

加载指定广告单元的广告内容。必须在调用 show 之前先调用 load。

参数

描述

adUnitId

要加载广告内容的广告单元的标识符。

loadOptions

一组用于修改广告行为的选项。

listener

（可选）使用 IUnityAdsLoadListener 回调加载广告内容（3.7.0 和更高版本）。

show

public static void show(final Activity activity, final String adUnitId, final UnityAdsShowOptions options, final IUnityAdsShowListener showListener)

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

参数

描述

activity

当前 Android Activity。

adUnitId

要展示的广告单元的标识符。

options

一组用于修改广告行为的选项。

showListener

（可选）使用 IUnityAdsShowListener 回调展示广告内容（3.7.0 和更高版本）。

addListener

[!WARNING]已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

public static void addListener(IUnityAdsListener listener)

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

参数

描述

listener

用于 Unity Ads 回调的监听器。

removeListener

[!WARNING]已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

public static void removeListener(IUnityAdsListener listener)

移除活动 IUnityAdsListener。

参数

描述

listener

用于 Unity Ads 回调的监听器。

getVersion

public static String getVersion()

返回当前 Ads SDK 版本。

getPlacementState

public static PlacementState getPlacementState(String adUnitId)

返回指定广告单元的状态。

参数

描述
adUnitId

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

setDebugMode

public static void setDebugMode(boolean debugMode)

控制 SDK 的日志输出量。设置为 true 可获得更详细完整的日志记录。

getDebugMode

public static boolean getDebugMode()

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

isInitialized

public static boolean isInitialized()

如果 SDK 已成功初始化，返回 true，否则返回 false。

isSupported

public static bool isSupported()

如果 SDK 在当前平台上受支持，返回 true，否则返回 false。

UnityAdsLoadOptions

public class UnityAdsLoadOptions extends UnityAdsBaseOptions

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

setAdMarkup

public void setAdMarkup(String adMarkup)

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

setObjectId

public void setObjectId(String objectId)

此方法将加载的广告对象 ID 设置为要展示的广告对象 ID。

BannerView

public BannerView(Activity activity, String adUnitId, UnityBannerSize size)

String mObjectId = UUID.randomUUID().toString();UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();loadOptions.setAdMarkup(markup);loadOptions.setObjectId(mObjectId);UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

参数

描述

activity

当前 Android Activity。

adUnitId

要展示的广告单元的标识符。

size

横幅对象的大小。

getPlacementId

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

返回横幅广告单元的 Ad Unit ID（广告单元 ID）。

getSize

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

横幅的 size。

setListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

设置横幅广告的活动监听器。

getListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

获取横幅广告的活动监听器。

load

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

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

destroy

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

不再使用横幅时，调用此方法可将其从 View 层级视图中删除。

UnityBannerSize

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

使用此类可以定义横幅对象的高度和宽度。

getWidth

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

返回横幅对象的宽度（以像素为单位）。

getHeight

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

返回横幅对象的高度（以像素为单位）。

枚举

PlacementState

广告单元的状态枚举。

值

描述

READY

广告单元已准备好展示广告。

NOT_AVAILABLE

广告单元不可用。

DISABLED

已禁用广告单元。

WAITING

广告单元正在等待准备就绪。

NO_FILL

广告单元没有要展示的广告。

FinishState

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

值

描述

ERROR

表示由于 Unity 服务错误而未能播放完广告。

SKIPPED

表示用户跳过了广告。

COMPLETED

表示用户已成功看完广告。

UnityAdsInitializationError

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

值

描述

INTERNAL_ERROR

由于环境或内部服务而发生错误。

INVALID_ARGUMENT

由于 initialize 方法中的参数无效而发生错误。

AD_BLOCKER_DETECTED

由于 URL 被阻止而发生错误。

UnityAdsShowCompletionState

广告已结束的原因枚举。

值

描述

SKIPPED

表示用户跳过了广告。

COMPLETED

表示广告已完整播放。这通常表明用户可以因观看完整的广告而获得奖励。

UnityAdsLoadError

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

值

描述

INITIALIZE_FAILED

由于 SDK 未初始化而导致广告加载失败。

INTERNAL_ERROR

由于内部 Unity Ads 服务错误而导致广告加载失败。

INVALID_ARGUMENT

由于 load 方法中的参数无效而导致广告加载失败。

NO_FILL

由于广告平台上没有可用的内容而导致广告加载失败。

TIMEOUT

广告未能在指定的时间范围内加载。

UnityAdsShowError

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

值

描述

NOT_INITIALIZED

由于 SDK 未初始化而导致广告展示失败。

NOT_READY

由于广告单元尚未准备就绪而导致广告展示失败。

VIDEO_PLAYER_ERROR

由于媒体播放器错误而导致广告展示失败。

INVALID_ARGUMENT

由于 show 方法中的参数无效而导致广告展示失败。

NO_CONNECTION

由于互联网连接错误而导致广告展示失败。

ALREADY_SHOWING

由于广告已在展示而导致广告展示失败。

INTERNAL_ERROR

由于内部 Unity Ads 服务错误而导致广告展示失败。

UnityAdsError

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

广告失败的原因枚举。

接口

IUnityAdsInitializationListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

实现此接口可以处理 initialize 结果。

onInitializationComplete

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

onInitializationFailed

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

参数

描述

error

导致初始化失败的 UnityAdsInitializationError。

message

与错误相关的消息。

IUnityAdsLoadListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

实现此接口可以处理 load 结果。

onUnityAdsAdLoaded

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

参数

描述

adUnitId

已加载内容的广告单元的标识符。

onUnityAdsFailedToLoad

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

参数

描述

adUnitId

内容加载失败的广告单元的标识符。

error

导致加载失败的 UnityAdsLoadError。

message

与错误相关的消息。

IUnityAdsShowListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

实现此接口可以处理 show 结果。

onUnityAdsShowFailure

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

参数

描述

adUnitId

展示内容失败的广告单元的标识符。

error

导致展示失败的 UnityAdsShowError。

message

与错误相关的消息。

onUnityAdsShowStart

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

参数

描述

adUnitId

展示内容的广告单元的标识符。

onUnityAdsShowClick

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

参数

描述

adUnitId

展示内容的广告单元的标识符。

onUnityAdsShowComplete

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

参数

描述

adUnitId

展示内容的广告单元的标识符。

showCompletionState

表示广告已跳过或完成。

IUnityAdsListener

[!WARNING]已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

实现此接口可以处理各种广告状态。在脚本中实现此监听器可以定义奖励广告的逻辑。

onUnityAdsReady

[!WARNING]已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

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

参数

描述

adUnitId

已准备就绪的广告单元的标识符。

onUnityAdsDidError

[!WARNING]已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

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

参数

描述

error

导致广告失败的错误。

message

与错误相关的消息。

onUnityAdsDidStart

[!WARNING]已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

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

参数

描述

adUnitId

正在展示广告的广告单元的标识符。

OnUnityAdsDidFinish

[!WARNING]已在 SDK 4.0 版本中移除。有关详细信息，请参阅已弃用的 API 类。

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

参数

描述

adUnitId

完成广告展示的广告单元的标识符。

result

广告展示的结果用户事件。

IListener

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

此接口授予对横幅广告生命周期事件的访问权限。此外，您可以实现以下重载方法：

String mObjectId = UUID.randomUUID().toString();
				UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
				loadOptions.setAdMarkup(markup);
				loadOptions.setObjectId(mObjectId);
			UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

onBannerLoaded

横幅完成广告加载时触发此回调。view 参数将引用应插入 View 层级视图中的横幅。

参数

描述

bannerAdView

加载的横幅对象。

onBannerClick

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

参数

描述

bannerAdView

加载的横幅对象。

onBannerError

在横幅广告展示过程中发生错误时触发此回调。

参数

描述

bannerAdView

加载的横幅对象。

errorInfo

一个包含横幅广告加载错误相关信息的类。

onBannerLeftApplication

横幅广告链接到应用程序外部时触发此回调。

参数

描述

bannerAdView

加载的横幅对象。

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.