Unity Ads SDK API 参考 • Unity Grow

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


using UnityEngine.Advertisements;

本文包含以下 API 文档：

类

Advertisement
Banner
BannerLoadOptions
BannerOptions
ShowOptions

枚举

ShowResult
UnityAdsInitializationError
UnityAdsLoadError
UnityAdsShowError
UnityAdsShowCompletionState
BannerPosition

接口

IUnityAdsInitializationListener
IUnityAdsLoadListener
IUnityAdsShowListener

类
类

Advertisement
Advertisement

Initialize
Initialize


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

使用指定的 Game ID（游戏 ID）, 测试模式状态以及广告单元加载设置来初始化广告服务。

参数	描述
`gameId`	开发者后台中项目的特定于平台的 Unity Game ID（Unity 游戏 ID）。
`testMode`	使用测试模式可以在不投放真实广告的情况下测试集成情况。使用 `true` 在测试模式下进行初始化。
`initializationListener`	（可选）使用 `IUnityAdsInitializationListener` 回调启用 SDK（3.7.0 和更高版本）。

Load
Load


public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)

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

参数	描述
`adUnitId`	要加载广告内容的广告单元的标识符。
`loadListener`	（可选）使用 `IUnityAdsLoadListener` 回调加载广告内容（3.7.0 和更高版本）。

IsReady
IsReady

Important

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


static bool IsReady (string adUnitId)

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

参数	描述
`adUnitId`	要查询的广告单元的标识符。

Show
Show


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

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

参数	描述
`adUnitId`	要展示的广告单元的标识符。
`showOptions`	一组用于修改广告展示行为的选项（包括 `resultCallback`）。
`showListener`	（可选）使用 `IUnityAdsShowListener` 回调展示广告内容（3.7.0 和更高版本）。

Note

如果在未指定 Ad Unit ID（广告单元 ID）的情况下调用 Show，则该方法会展示 Unity 标准广告位中加载的内容。在 SDK 4.0 及更高版本中，必须指定 ad unit ID（广告单元 ID）。

AddListener
AddListener

Important

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


public static void AddListener(IUnityAdsListener listener)

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

参数	描述
`listener`	用于 Unity Ads 回调的监听器。

RemoveListener
RemoveListener

Important

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


public static void RemoveListener(IUnityAdsListener listener)

移除活动 IUnityAdsListener。

参数	描述
`listener`	用于 Unity Ads 回调的监听器。

GetPlacementState
GetPlacementState

Important

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


public static PlacementState GetPlacementState(string adUnitId)

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

参数	描述
`adUnitId`	要查询的广告单元的标识符。

isInitialized
isInitialized


public static bool isInitialized

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

isSupported
isSupported


public static bool isSupported

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

debugMode
debugMode


public static bool debugMode

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

version
version


public static string version

返回当前 SDK 版本。

isShowing
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)

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

SetPosition
SetPosition


public void SetPosition (BannerPosition bannerPosition)

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

参数	描述
`bannerPosition`	用作横幅广告锚点的位置。


public static bool isLoaded

如果当前加载了要展示的横幅广告，返回 true，否则返回 false。

ShowOptions
ShowOptions

实现这些选项可以在广告单元中展示内容时向 SDK 通知相关事件。当广告结束时，使用 ShowOptions.resultCallback 将 ShowResult 枚举返回给 Show。

resultCallback
resultCallback


public ShowResult resultCallback { get; set; }

此回调接收广告的结果。

Important

改而实现 IUnityAdsListener 并调用 Advertisement.AddListener。

gamerSid
gamerSid


public string gamerSid { get; set; }

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

BannerLoadOptions
BannerLoadOptions

实现这些选项可以在加载横幅广告时向 SDK 通知相关事件。

loadCallback
loadCallback


public LoadCallback loadCallback { get; set; }

横幅广告单元成功加载已准备好展示的内容时触发此回调。

errorCallback
errorCallback


public ErrorCallback errorCallback { get; set; }

横幅广告单元加载内容失败时触发此回调。

BannerOptions
BannerOptions

实现这些选项可以在展示横幅广告时向 SDK 通知相关事件。

bannerCallback
bannerCallback


public BannerCallback bannerCallback { get; set; }

横幅广告对用户可见时触发此回调。

hideCallback
hideCallback


public BannerCallback hideCallback { get; set; }

横幅广告对用户不可见时触发此回调。

clickCallback
clickCallback


public BannerCallback clickCallback { get; set; }

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

枚举
枚举

PlacementState
PlacementState

Important

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

广告单元的状态枚举。

值	描述
`Ready`	广告单元已准备好展示广告。
`NotAvailable`	广告单元不可用。
`Disabled`	已禁用广告单元。
`Waiting`	广告单元正在等待准备就绪。
`NoFill`	广告单元没有可展示的广告。

ShowResult
ShowResult

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

值	描述
`Failed`	表示由于 Unity 服务错误而未能播放完广告。
`Skipped`	表示用户跳过了广告。
`Finished`	表示用户已成功看完广告。

UnityAdsInitializationError
UnityAdsInitializationError

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

值	描述
`UNKNOWN`	由于未知原因而发生错误。
`INTERNAL_ERROR`	由于环境或内部服务而发生错误。
`INVALID_ARGUMENT`	由于 `Initialize` 方法中的参数无效而发生错误。
`AD_BLOCKER_DETECTED`	由于 URL 被阻止而发生错误。

UnityAdsLoadError
UnityAdsLoadError

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

值	描述
`INITIALIZE_FAILED`	由于 SDK 未初始化而导致广告加载失败。
`INTERNAL_ERROR`	由于内部 Unity Ads 服务错误而导致广告加载失败。
`INVALID_ARGUMENT`	由于 `Load` 方法中的参数无效而导致广告加载失败。
`NO_FILL`	由于广告平台上没有可用的内容而导致广告加载失败。
`TIMEOUT`	广告未能在指定的时间范围内加载。
`UNKNOWN`	由于未知原因而导致广告加载失败。

UnityAdsShowCompletionState
UnityAdsShowCompletionState

广告已结束的原因枚举。

值	描述
`SKIPPED`	表示用户跳过了广告。
`COMPLETED`	表示广告已完整播放。这通常表明用户可以因观看完整的广告而获得奖励。
`UNKNOWN`	广告结束的原因未知。

UnityAdsShowError
UnityAdsShowError

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

值	描述
`NOT_INITIALIZED`	由于 SDK 未初始化而导致广告展示失败。
`NOT_READY`	由于广告单元尚未准备就绪而导致广告展示失败。
`VIDEO_PLAYER_ERROR`	由于媒体播放器错误而导致广告展示失败。
`INVALID_ARGUMENT`	由于 `Show` 方法中的参数无效而导致广告展示失败。
`NO_CONNECTION`	由于互联网连接错误而导致广告展示失败。
`ALREADY_SHOWING`	由于广告已在展示而导致广告展示失败。
`INTERNAL_ERROR`	由于内部 Unity Ads 服务错误而导致广告展示失败。
`UNKNOWN`	由于未知原因而导致广告展示失败。

BannerPosition
BannerPosition

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

值	描述
`TOP_LEFT`	将横幅广告锚定在屏幕的左上角。
`TOP_CENTER`	将横幅广告锚定在屏幕的顶部中央位置。
`TOP_RIGHT`	将横幅广告锚定在屏幕的右上角。
`BOTTOM_LEFT`	将横幅广告锚定在屏幕的左下角。
`BOTTOM_CENTER`	将横幅广告锚定在屏幕的底部中央位置。
`BOTTOM_RIGHT`	将横幅广告锚定在屏幕的右下角。
`CENTER`	将横幅广告锚定在屏幕的中央位置。

接口
接口

IUnityAdsInitializationListener
IUnityAdsInitializationListener


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

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

OnInitializationComplete
OnInitializationComplete

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

OnInitializationFailed
OnInitializationFailed

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

参数	描述
`error`	导致初始化失败的 `UnityAdsInitializationError`。
`message`	与错误相关的消息。

IUnityAdsLoadListener
IUnityAdsLoadListener


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

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

OnUnityAdsLoaded
OnUnityAdsLoaded

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

参数	描述
`adUnitId`	已加载内容的广告单元的标识符。

OnUnityAdsFailedToLoad
OnUnityAdsFailedToLoad

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

参数	描述
`adUnitId`	加载失败的广告单元的标识符。
`error`	导致加载失败的 `UnityAdsLoadError`。
`message`	与错误相关的消息。

IUnityAdsShowListener
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
OnUnityAdsShowFailure

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

参数	描述
`adUnitId`	展示失败的广告单元的标识符。
`error`	导致展示失败的 `UnityAdsShowError`。
`message`	与错误相关的消息。

OnUnityAdsShowStart
OnUnityAdsShowStart

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

参数	描述
`adUnitId`	展示内容的广告单元的标识符。

OnUnityAdsShowClick
OnUnityAdsShowClick

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

参数	描述
`adUnitId`	展示内容的广告单元的标识符。

OnUnityAdsShowComplete
OnUnityAdsShowComplete

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

参数	描述
`adUnitId`	展示内容的广告单元的标识符。
`showCompletionState`	表示广告的最终状态（广告已跳过或完成）。

IUnityAdsListener
IUnityAdsListener

Important

已在 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
OnUnityAdsReady

Important

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

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

参数	描述
`adUnitId`	已准备就绪的广告单元的标识符。

OnUnityAdsDidError
OnUnityAdsDidError

Important

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

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

参数	描述
`message`	与错误相关的消息。

OnUnityAdsDidStart
OnUnityAdsDidStart

Important

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

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

参数	描述
`adUnitId`	正在展示内容的广告单元的标识符。

OnUnityAdsDidFinish
OnUnityAdsDidFinish

Important

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

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

参数	描述
`adUnitId`	完成广告展示的广告单元的标识符。
`showResult`	广告展示的结果用户事件。

类类

AdvertisementAdvertisement

InitializeInitialize

LoadLoad

IsReadyIsReady

ShowShow

AddListenerAddListener

RemoveListenerRemoveListener

GetPlacementStateGetPlacementState

isInitializedisInitialized

isSupportedisSupported

debugModedebugMode

versionversion

isShowingisShowing

横幅广告横幅广告

LoadLoad

ShowShow

HideHide

SetPositionSetPosition

isLoadedisLoaded

ShowOptionsShowOptions

resultCallbackresultCallback

gamerSidgamerSid

BannerLoadOptionsBannerLoadOptions

loadCallbackloadCallback

errorCallbackerrorCallback

BannerOptionsBannerOptions

bannerCallbackbannerCallback

hideCallbackhideCallback

clickCallbackclickCallback

枚举枚举

PlacementStatePlacementState

ShowResultShowResult

UnityAdsInitializationErrorUnityAdsInitializationError

UnityAdsLoadErrorUnityAdsLoadError

UnityAdsShowCompletionStateUnityAdsShowCompletionState

UnityAdsShowErrorUnityAdsShowError

BannerPositionBannerPosition

接口接口

IUnityAdsInitializationListenerIUnityAdsInitializationListener

OnInitializationCompleteOnInitializationComplete

OnInitializationFailedOnInitializationFailed

IUnityAdsLoadListenerIUnityAdsLoadListener

OnUnityAdsLoadedOnUnityAdsLoaded

OnUnityAdsFailedToLoadOnUnityAdsFailedToLoad

IUnityAdsShowListenerIUnityAdsShowListener

OnUnityAdsShowFailureOnUnityAdsShowFailure

OnUnityAdsShowStartOnUnityAdsShowStart

OnUnityAdsShowClickOnUnityAdsShowClick

OnUnityAdsShowCompleteOnUnityAdsShowComplete

IUnityAdsListenerIUnityAdsListener

OnUnityAdsReadyOnUnityAdsReady

OnUnityAdsDidErrorOnUnityAdsDidError

OnUnityAdsDidStartOnUnityAdsDidStart

OnUnityAdsDidFinishOnUnityAdsDidFinish

类
类

Advertisement
Advertisement

Initialize
Initialize

Load
Load

IsReady
IsReady

Show
Show

AddListener
AddListener

RemoveListener
RemoveListener

GetPlacementState
GetPlacementState

isInitialized
isInitialized

isSupported
isSupported

debugMode
debugMode

version
version

isShowing
isShowing

横幅广告
横幅广告

Load
Load

Show
Show

Hide
Hide

SetPosition
SetPosition

isLoaded
isLoaded

ShowOptions
ShowOptions

resultCallback
resultCallback

gamerSid
gamerSid

BannerLoadOptions
BannerLoadOptions

loadCallback
loadCallback

errorCallback
errorCallback

BannerOptions
BannerOptions

bannerCallback
bannerCallback

hideCallback
hideCallback

clickCallback
clickCallback

枚举
枚举

PlacementState
PlacementState

ShowResult
ShowResult

UnityAdsInitializationError
UnityAdsInitializationError

UnityAdsLoadError
UnityAdsLoadError

UnityAdsShowCompletionState
UnityAdsShowCompletionState

UnityAdsShowError
UnityAdsShowError

BannerPosition
BannerPosition

接口
接口

IUnityAdsInitializationListener
IUnityAdsInitializationListener

OnInitializationComplete
OnInitializationComplete

OnInitializationFailed
OnInitializationFailed

IUnityAdsLoadListener
IUnityAdsLoadListener

OnUnityAdsLoaded
OnUnityAdsLoaded

OnUnityAdsFailedToLoad
OnUnityAdsFailedToLoad

IUnityAdsShowListener
IUnityAdsShowListener

OnUnityAdsShowFailure
OnUnityAdsShowFailure

OnUnityAdsShowStart
OnUnityAdsShowStart

OnUnityAdsShowClick
OnUnityAdsShowClick

OnUnityAdsShowComplete
OnUnityAdsShowComplete

IUnityAdsListener
IUnityAdsListener

OnUnityAdsReady
OnUnityAdsReady

OnUnityAdsDidError
OnUnityAdsDidError

OnUnityAdsDidStart
OnUnityAdsDidStart

OnUnityAdsDidFinish
OnUnityAdsDidFinish