Unity Ads SDK API 参考

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

using UnityEngine.Advertisements;

本文包含以下 API 文档

类

枚举

接口

类

初始化

public static void Initialize(string gameId, bool testMode, IUnityAdsInitializationListener initializationListener)

初始化广告服务，指定 游戏 ID、测试模式 状态和 广告单元 加载设置。

参数

描述

gameId

您项目平台特定的 Unity 游戏标识符，可在开发者控制面板中找到。

testMode

使用测试模式在不投放实时广告的情况下测试您的集成。使用 true 在测试模式下初始化。

initializationListener

可以选择使用 IUnityAdsInitializationListener 回调（版本 3.7.0 及更高版本）来启用 SDK。

加载

public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)

为指定的 广告单元 加载广告内容。

参数

描述

adUnitId

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

loadListener

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

已准备

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

static bool IsReady (string adUnitId)

如果广告已准备好在指定的 广告单元 中显示，则返回 true。如果您使用启用的 enablePerPlacementLoad 初始化了 SDK，则必须在调用 Show 之前调用 Load。

参数

描述

adUnitId

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

显示

public static void Show(string adUnitId, ShowOptions showOptions, IUnityAdsShowListener showListener)

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

参数

描述

adUnitId

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

showOptions

包含 resultCallback 的选项集合，用于修改广告行为。

showListener

可以选择使用 IUnityAdsShowListener 回调（版本 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 specify an Ad Unit ID.

添加监听器

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

public static void AddListener(IUnityAdsListener listener)

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

参数

描述

listener

用于 Unity Ads 回调的 监听器。

删除监听器

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

public static void RemoveListener(IUnityAdsListener listener)

移除活动的 IUnityAdsListener。

参数

描述

listener

用于 Unity Ads 回调的监听器。

获取放置状态

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

public static PlacementState GetPlacementState(string adUnitId)

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

参数

描述

adUnitId

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

isInitialized

public static bool isInitialized

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

isSupported

public static bool isSupported

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

debugMode

public static bool debugMode

如果 SDK 处于调试模式，则返回 true，否则返回 false。调试模式控制 SDK 的日志记录级别。

版本

public static string version

返回当前 SDK 版本。

isShowing

public static bool isShowing

如果广告当前正在显示，则返回 true，否则返回 false。

使用此类来 实现横幅广告。

加载

public static void Load(string adUnitId, BannerLoadOptions options)

为指定的横幅 广告单元 加载广告内容。如果您使用启用的 enablePerPlacementLoad 初始化了 SDK，则必须在调用 Show 之前调用 Load。

参数

描述

adUnitId

要加载的横幅广告单元的标识符。

options

一组 选项，在加载横幅时通知 SDK 事件。

显示

public static void Show(string adUnitId, BannerOptions options)

显示指定的横幅 广告单元 的广告内容。您必须在调用 Show 之前调用 Load。

参数

描述

adUnitId

要加载的横幅广告单元的标识符。

options

一组 选项，在显示横幅时通知 SDK 事件。

隐藏

public static void Hide(bool destroy = false)

允许您隐藏横幅广告，而不完全销毁它。

设置位置

public void SetPosition (BannerPosition bannerPosition)

设置设备上横幅广告的位置。

参数

描述

bannerPosition

用作横幅广告锚点的 位置。

isLoaded

public static bool isLoaded

如果横幅广告当前已加载，可以显示，则返回 true，否则返回 false。

显示选项

实现这些选项，在广告单元中显示内容时通知 SDK 事件。使用 ShowOptions.resultCallback 将 ShowResult 枚举传回 Show，以便在广告结束时执行。

resultCallback

public ShowResult resultCallback { get; set; }

此回调接收广告的结果。

已弃用：实现 IUnityAdsListener 并调用 Advertisement.AddListener 代替。

gamerSid

public string gamerSid { get; set; }

指定游戏中特定用户的标识符。

横幅加载选项

实现这些选项，在加载横幅广告时通知 SDK 事件。

loadCallback

public LoadCallback loadCallback { get; set; }

当横幅 广告单元 成功加载可以显示的内容时，此回调将触发。

errorCallback

public ErrorCallback errorCallback { get; set; }

当横幅 广告单元 无法加载内容时，此回调将触发。

横幅选项

实现这些选项，在显示横幅广告时通知 SDK 事件。

bannerCallback

public BannerCallback bannerCallback { get; set; }

当横幅对用户可见时，此回调将触发。

hideCallback

public BannerCallback hideCallback { get; set; }

当横幅对用户隐藏时，此回调将触发。

clickCallback

public BannerCallback clickCallback { get; set; }

当用户点击横幅时，此回调将触发。

枚举

放置状态

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

广告单元 的枚举状态。

值

描述

已准备

广告单元已准备显示广告。

不可用

广告单元不可用。

已禁用

广告单元已被禁用。

等待中

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

NoFill

广告单元没有广告可供展示。

ShowResult

用户与广告交互的枚举状态。当广告完成时，SDK 会将此值传递到 OnUnityAdsDidFinish 回调方法中。

值

描述

Failed

表示由于 Unity 服务错误导致广告无法完成。

Skipped

表示用户跳过了广告。

Finished

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

UnityAdsInitializationError

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

值

描述

UNKNOWN

由于未知原因导致错误。

INTERNAL_ERROR

由于环境或内部服务导致错误。

INVALID_ARGUMENT

由于 Initialize 方法中的参数无效导致错误。

AD_BLOCKER_DETECTED

由于 URL 被阻止导致错误。

UnityAdsLoadError

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

值

描述

INITIALIZE_FAILED

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

INTERNAL_ERROR

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

INVALID_ARGUMENT

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

NO_FILL

由于网络上没有可用内容，导致广告加载失败。

TIMEOUT

广告在指定时间范围内未加载完成。

UNKNOWN

由于未知原因导致广告加载失败。

UnityAdsShowCompletionState

广告完成的枚举原因。

值

描述

SKIPPED

表示用户跳过了广告。

COMPLETED

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

UNKNOWN

广告完成的原因未知。

UnityAdsShowError

广告无法展示的枚举原因。

值

描述

NOT_INITIALIZED

由于 SDK 未初始化导致广告无法展示。

NOT_READY

由于广告单元未准备就绪导致广告无法展示。

VIDEO_PLAYER_ERROR

由于媒体播放器错误导致广告无法展示。

INVALID_ARGUMENT

由于 Show 方法中的参数无效导致广告无法展示。

NO_CONNECTION

由于互联网连接错误导致广告无法展示。

ALREADY_SHOWING

由于已经有广告正在展示导致广告无法展示。

INTERNAL_ERROR

由于内部 Unity Ads 服务错误导致广告无法展示。

UNKNOWN

由于未知原因导致广告无法展示。

BannerPosition

在设备显示屏上锚定横幅的枚举位置。

值

描述

TOP_LEFT

将横幅锚定到屏幕的左上角。

TOP_CENTER

将横幅锚定到屏幕的顶部中央。

TOP_RIGHT

将横幅锚定到屏幕的右上角。

BOTTOM_LEFT

将横幅锚定到屏幕的左下角。

BOTTOM_CENTER

将横幅锚定到屏幕的底部中央。

BOTTOM_RIGHT

将横幅锚定到屏幕的右下角。

CENTER

将横幅锚定到屏幕的中央。

Interfaces

IUnityAdsInitializationListener

public interface IUnityAdsInitializationListener {
    void OnInitializationComplete();
    void OnInitializationFailed(UnityAdsInitializationError error, string message);
}

实现此接口以处理 Initialize 结果。

OnInitializationComplete

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

OnInitializationFailed

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

参数

描述

error

导致初始化失败的 UnityAdsInitializationError。

message

与错误关联的消息。

IUnityAdsLoadListener

public interface IUnityAdsLoadListener {
    void OnUnityAdsAdLoaded(string adUnitId);
    void OnUnityAdsFailedToLoad(string adUnitId, UnityAdsLoadError error, string message);
}

实现此接口以处理 Load 结果。

OnUnityAdsLoaded

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

参数

描述

adUnitId

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

OnUnityAdsFailedToLoad

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

参数

描述

adUnitId

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

error

导致加载失败的 UnityAdsLoadError。

message

与错误关联的消息。

IUnityAdsShowListener

public interface IUnityAdsShowListener {
    void OnUnityAdsShowFailure(string adUnitId, UnityAdsShowError error, string message);
    void OnUnityAdsShowStart(string adUnitId);
    void OnUnityAdsShowClick(string adUnitId);
    void OnUnityAdsShowComplete(string adUnitId, UnityAdsShowCompletionState showCompletionState);
}

实现此接口以处理 Show 结果。

OnUnityAdsShowFailure

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

参数

描述

adUnitId

无法展示的广告单元的标识符。

error

导致展示失败的 UnityAdsShowError。

message

与错误关联的消息。

OnUnityAdsShowStart

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

参数

描述

adUnitId

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

OnUnityAdsShowClick

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

参数

描述

adUnitId

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

OnUnityAdsShowComplete

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

参数

描述

adUnitId

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

showCompletionState

表示广告的最终 状态（广告是被跳过还是被完整观看）。

IUnityAdsListener

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

public interface IUnityAdsListener
{
    void OnUnityAdsReady(string adUnitId);
    void OnUnityAdsDidError(string message);
    void OnUnityAdsDidStart(string adUnitId);
    void OnUnityAdsDidFinish(string adUnitId, ShowResult showResult);
}

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

OnUnityAdsReady

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

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

参数

描述

adUnitId

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

OnUnityAdsDidError

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

指定由于错误导致广告内容无法展示的逻辑。

参数

描述

message

与错误关联的消息。

OnUnityAdsDidStart

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

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

参数

描述

adUnitId

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

OnUnityAdsDidFinish

已在 SDK 版本 4.0 中移除。有关更多信息，请参阅 已弃用的 API 类。

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

参数

描述

adUnitId

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

showResult

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

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.