Vungle - Windows SDK v. 5 入门指南

使用本指南,快速将 SDK 集成到您的应用中,并开始获利。

本指南中的代码示例是 C#,但我们在 GitHub 存储库中提供的示例应用文件包括 C#、C++、Visual Basic 和 DirectX+XAML。

目录

开始之前

  • 本指南适用于 Vungle Windows SDK 5.3.2 及更高版本。有关 Vungle Windows SDK 1.3.16 及更低版本的集成指南,请查阅:Vungle - Windows SDK v. 1.0 - v.1.3.16 入门指南
  • 集成需要您拥有 Vungle 帐户,如果还没有,请创建 Vungle 帐户
  • 如果尚未执行此操作,请前往管理面板,将您的应用添加到帐户中。请查看广告位置的设置和报告了解如何在 Vungle 管理面板中设置广告位置。
  • 如果针对 Windows 8.1 和 Windows Phone 8.1 进行开发,则必须使用 Visual Studio 2015,因为 Visual Studio 2017 已停止支持这些版本。
  • 移动设备支持“返回”按钮,但台式电脑(键盘)上不支持。这可能带来 UWP 版本的不同行为和用户体验。
  • 如果在“测试”模式下没有广告返回,请将您的应用程序切换到“活动”模式。

下载 SDK 并将 VungleSDK 添加到您的项目中

您可以采用两种方法将 Vungle 添加到 Visual Studio 项目中:使用 NuGet 或手动集成。

选项 1:NuGet 集成

  1. 在 Visual Studio 中,右键单击“项目”,然后选择“管理 NuGet 程序包”
  2. 单击“浏览”,输入“Vungle”,选择“Vungle SDK”,然后单击“安装”

选项 2:手动集成

  1. 从 Vungle 管理面板下载 Vungle Windows SDK
  2. 解压存档文件。
  3. 在 Visual Studio 中,使用适合您的应用程序和编程语言的相应模板创建新项目。
  4. 将项目引用添加到已下载的 Vungle Windows SDK 文件中。

Vungle SDK 有两个 VungleSDK.windmd 文件,分别用于针对 Windows 10 和 Windows 8.1 进行的开发。请从以下提取路径选择正确的 SDK 文件:Win10Win81

internetClient 功能

确保您的项目在 package.appxmanifest 文件中具有 internetClient 功能。

Visual Studio

  1. 双击“解决方案资源管理器”中的 appxmanifest
  2. 选择“功能”
  3. 确认已勾选“Internet (客户端)”选项。

手动编辑

打开 package.appxmanifeset 文件并将 internetClient 添加到“功能”部分。

<Capabilities>
...
<Capability Name="internetClient" />
...
</Capabilities>

导入 VungleSDK 命名空间

using VungleSDK;

获取 VungleAd 实例

VungleAd 实例采用两个参数:一个是您的 Vungle 应用 ID 字符串,一个是广告位置 ID 的字符串数组。您仅可使用在获取实例时已包括在内的广告位置 ID。如果未包括任何自动缓存的广告位置,SDK 会自动将一个非自动缓存广告位置分配为自动缓存。

VungleAd sdkInstance; string appID = “app_id”; string[] placementArray = new string[] { “placement_id_1”, “placement_id_2”, “placement_id_3” };
sdkInstance = AdFactory.GetInstance(appID, placementArray);

在上例中,将 app_id 替换为您的 Vungle 应用 ID,将 placement_id_# 替换为您项目的广告位置 ID。建议您在应用程序完成重要组件加载后立即执行这些初始化步骤,以便自动缓存更快启动。

创建并注册事件处理程序

创建适用于 OnAdPlayableChanged 事件的事件处理程序。当广告可用性状态改变时调用此事件处理程序。您可以通过检查 e.Placement 来确定哪个广告位置触发了事件。

//OnAdPlayableChanged 事件的事件处理程序 private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { // e.Placement - 字符串中的广告位置 ID //在 UI 线程上异步运行 await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => methodToRun(e.Placement))); } 

注册该适用于 OnAdPlayableChanged 事件的事件处理程序。

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; 

为广告位置加载广告

对于非自动缓存的广告位置,您必须先调用 LoadAd,留出足够时间下载广告资产,然后等待 OnAdPlayableChanged 被调用:

sdkInstance.LoadAd(“placement_id”); 

注意:自动缓存广告位置将尝试在调用 PlayAdAsync 后立即下载新的广告资产,因此无需调用 LoadAd

示例代码:

private void OnLevelStart(Object sender, RoutedEventArgs e) { sdkInstance.LoadAd(“placement_id”); } 

播放广告

使用默认配置播放广告:

sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”); 

示例代码:

private async void OnLevelComplete(Object sender, RoutedEventArgs e) { await sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”); } 

(可选)您可以通过向 AdConfig 对象提供选项来自定义所播放的广告。

示例代码:

private async void PlayCustomizedAd(Object sender, RoutedEventArgs e) { AdConfig adConfig = new AdConfig(); adConfig.Orientation = DisplayOrientations.Portrait; adConfig.SoundEnabled = false; await sdkInstance.PlayAdAsync(adConfig, placement2); } 

自定义选项

以下是 AdConfig 对象实例中的可用属性:

注意:奖励式广告在有些情况下又称为激励式广告;这两个术语实际指的是同一类广告。在 SDK 代码和报告 API 中,我们统一使用“激励式”广告这一术语。

选项

默认值/类型

说明

Orientation

AutoRotate

DisplayOrientations

Orientation.AutoRotate(默认)可让广告随设备方向自动旋转。

Orientation.Portrait 可让广告只纵向播放。

Orientation.Landscape 可让广告只横向播放。

注意:此选项仅适用于移动应用程序。

SoundEnabled

true

布尔值

设置广告开始时的声音状态。

如果为 true(默认),音频将遵循设备的音量和声音设定。

如果为 false,视频将静音播放,但用户可自行调节。

BackButtonImmediatelyEnabled

false

布尔值

如果为 true,用户可以使用返回按钮立即退出广告。

如果为 false(默认),用户在屏幕上显示“关闭”按钮之前无法使用“返回”按钮退出广告。

注意:此选项仅适用于移动应用程序。

UserId

null

字符串

在使用服务器到服务器回调进行验证时,将唯一用户 ID 传递至您的应用程序,以验证该用户因观看激励式广告所应获得的奖励。

注意:此设置仅适用于有奖励的广告位置。

IncentivizedDialogTitle

“关闭此广告?”

字符串

设置跳过激励式广告时的确认对话窗口标题。

注意:此设置仅适用于有奖励的广告位置。

IncentivizedDialogBody

“确定要跳过此广告吗?您必须看完广告才能获得奖励。”

字符串

设置跳过激励式广告时的确认对话窗口正文。

注意:此设置仅适用于有奖励的广告位置。

IncentivizedDialogCloseButton

“关闭”

 

字符串

设置跳过激励式广告时确认对话窗口中的“取消”按钮文字。

注意:此设置仅适用于有奖励的广告位置。

IncentivizedDialogContinueButton

“继续”

字符串

设置跳过激励式广告时确认对话窗口中的“继续观看”按钮文字。

注意:如果不是激励式广告,则该设置不适用。

Incentivized

-

已弃用

您可以从管理面板进行广告位置级别的奖励式配置。请参阅广告位置的设置和报告


注意:
Dynamic Template 与 Flex View 广告的 SoundEnabled 选项和激励式对话框可在管理面板上进行配置。编程配置仅适用于原有的广告。

显示“关闭”按钮

若要控制用户是否有权关闭广告,请在 Vungle 管理面板上使用应用程序高级设置中的强制观看选项。

订阅事件处理程序

Windows SDK 提供了一些您可以编程处理的事件。您可以使用这些事件处理程序控制应用程序的某些功能,例如暂停/继续播放背景音乐。

UI 线程注释

事件侦听器在后台线程中执行,因此任何由事件侦听器导致的 UI 交互或更新在执行之前都必须传递到主 UI 线程。以下是一种实现方法:

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ // This block will be executed in the UI thread
} );

VungleAd 事件处理程序

事件处理程序

说明

OnInitCompleted

在 SDK 完成初始化后立即调用。您可以检查是否有从之前会话下载的广告或为广告位置加载广告。

OnAdPlayableChanged

通知某一广告位置的广告可用性变化情况。在为广告位置加载广告后,等待此事件处理程序在广告可用时执行操作。

OnAdStart

在播放广告前调用。您可以执行相关操作,例如暂停背景音乐。

OnAdEnd

在用户关闭结束卡、控制转回至您的应用程序时调用。如果 IsCompletedViewCallToActionClicked 为 true,表明用户观看了广告或在广告中点击了下载按钮。这种情况下,如果是奖励式广告,用户应获得奖励。您可以执行相关操作,例如恢复应用功能。

Diagnostic

在 SDK 想要打印诊断日志时调用。

示例代码:

//Register event handlers sdkInstance.OnInitCompleted += SdkInstance_OnInitCompleted; sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; sdkInstance.OnAdStart += SdkInstance_OnAdStart; sdkInstance.OnAdEnd += SdkInstance_OnAdEnd; sdkInstance.Diagnostic += SdkInstance_Diagnostic; ... // OnInitCompleted // e.Initialized - true if initialization succeeded, false if failed // e.ErrorMessage - reason for failure when e.Initialized is false private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e) { var placementsInfo = "OnInitCompleted: " + e.Initialized; // Initilization was success if (e.Initialized == true) { // Print out list of placements for (var i = 0; i < e.Placements.Length; i++) { placementsInfo += "\n\tPlacement" + (i + 1) + ": " + e.Placements[i].ReferenceId; if (e.Placements[i].IsAutoCached == true) placementsInfo += " (Auto-Cached)"; } } // Initilization failed else { placementsInfo += "\n\t" + e.ErrorMessage; } System.Diagnostics.Debug.WriteLine(placementsInfo); await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => NotifyInitialization(e.Initialized))); } // OnAdPlayableAdPlayable // e.AdPlayable - true if an ad is available to play, false otherwise // e.Placement - placement ID in string private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { System.Diagnostics.Debug.WriteLine("OnAdPlayable(" + e.Placement + ") - " + e.AdPlayable); await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => NotifyWatcher(e.AdPlayable, e.Placement))); } // OnAdStart // e.Id - Vungle app ID in string // e.Placement - placement ID in string private void SdkInstance_OnAdStart(object sender, AdEventArgs e) { System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement); } // OnAdEnd // e.Id - Vungle app ID in string // e.Placement - placement ID in string // e.IsCompletedView- true when 80% or more of the video was watched // e.CallToActionClicked - true when the user has clicked download button on end card // e.WatchedDuration - DEPRECATED private void SdkInstance_OnAdEnd(object sender, AdEndEventArgs e) { System.Diagnostics.Debug.WriteLine("OnVideoEnd(" + e.Id + "): " + "\n\tPlacement: " + e.Placement + "\n\tIsCompletedView: " + e.IsCompletedView + "\n\tCallToActionClicked: " + e.CallToActionClicked + "\n\tWatchedDuration: " + e.WatchedDuration); } // Event handler called when SDK wants to print diagnostic logs private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e) { System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // DEPRECATED - Use SdkInstance_OnAdEnd() instead private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }

播放 Native Flex 广告

Vungle Windows SDK 5.1.0+ 支持我们全新的 Native Flex 广告功能。VungleAdControl 可通过 AdConfig.AdContainer 属性将自定义容器传递给 Vungle SDK,从而获得原生格式的视频广告,同时管理主应用程序的 Container.Content 的内容。

Native Flex 广告的要求

  • Windows SDK 5.1.0+
  • Windows 10 UWP

请咨询您的客户经理或联系 tech-support@vungle.com 来配置 Native Flex 广告的广告位置。

Native Flex 广告的用户界面设置 - XAML

声明 VungleAdControl 必须包含 Vungle 应用程序 ID、该应用中所用的全部广告位置 ID、以及此特定 Native Flex View 或 Feed 广告位置的广告位置 ID。您还可在此设置用于奖励式广告位置的 UserId

示例代码:

<Grid
<UI:VungleAdControl x:Name="vungleEmbedded"
Height="200"
Width="300"
AppID="vungle_app_id"
Placements="placement_id_1,placement_id_2,native_flex_id"
Placement = "native_flex_id"
UserId="vungle_test_user">
<TextBlock x:Name="Vungle Native Flex Ad"/>
</UI:VungleAdControl>
</Grid>

加载 Native Flex 广告

加载 Native Flex 广告位置的广告与加载全屏广告是一样的。

示例代码:

sdkInstance.LoadAd(“native_flex_id”); 

播放 Native Flex 广告

使用 Native Flex 广告位置播放广告与播放全屏广告类似,但必须通过 .xaml 文件或管理面板配置任何自定义,包括静音播放广告。

示例代码:

await vungleEmbedded.PlayAdAsync();

关闭 Native Flex 广告

鉴于 Native Flex 广告的性质,用户可以在不关闭广告的情况下停止观看视频。因此,必须告知 SDK 在屏幕上不再显示某广告时务必放弃该广告。为此,我们采用了两种关闭 Native Flex 广告的方法:

  • 使用 CloseFlexViewAd(String placementId) 可立即关闭指定广告位置 ID 的广告。

  • 使用 SetFlexViewCloseTimeInSec(String placementId, int seconds) 可在经过指定秒数后关闭指定的广告位置。

Native Flex 广告的事件处理程序

考虑注册独立的事件处理程序来管理不同的全屏和原生广告行为,以获得更流畅的用户体验。

示例代码:

vungleEmbedded.OnAdStart += (sender, arg) => { ... } vungleEmbedded.OnAdEnd += (sender, arg) => { ... } await vungleEmbedded.PlayAdAsync(); 
还有其它问题?提交请求

评论