使用本指南，快速将 SDK 集成到您的应用中，并开始获利。
本指南中的代码示例是 C#，但我们在 GitHub 存储库中提供的示例应用文件包括 C#、C++、Visual Basic 和 DirectX+XAML。
目录
- GDPR：推荐实施方法
- 开始之前
- 下载 SDK 并将 VungleSDK 添加到您的项目中
- 导入 VungleSDK 命名空间
- 获取 VungleAd 实例
- 创建并注册事件处理程序
- 为广告位置加载广告
- 为广告位置播放广告
- 自定义选项
- 订阅事件处理程序
- 播放 Native Flex 广告
GDPR：推荐实施方法
《通用数据保护条例》(GDPR) 将于 5 月 25 日在欧盟生效。为了遵守 GDPR，开发者有以下两种选择。
-
选项 1（推荐）：发布商从用户级别控制 GDPR 的同意流程，然后将用户的选择传达给 Vungle。为此，开发人员可以使用自己的机制来收集用户的同意信息，然后使用 Vungle API 更新或查询用户的同意状态。若需了解详细信息，请参阅“GDPR 推荐实施方法说明”部分。
- 选项 2：允许 Vungle 处理相关需求。Vungle 在向欧洲用户播放广告之前会显示征求同意的对话框，并记住用户的同意或拒绝选择，以用于后续的广告。
开始之前
- 本指南适用于 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 集成
- 在 Visual Studio 中，右键单击“项目”，然后选择“管理 NuGet 程序包”。
- 单击“浏览”，输入“Vungle”，选择“Vungle SDK”，然后单击“安装”。
选项 2：手动集成
- 从 Vungle 管理面板下载 Vungle Windows SDK。
- 解压存档文件。
- 在 Visual Studio 中，使用适合您的应用程序和编程语言的相应模板创建新项目。
- 将项目引用添加到已下载的 Vungle Windows SDK 文件中。
Vungle SDK 有两个 VungleSDK.windmd 文件，分别用于针对 Windows 10 和 Windows 8.1 进行的开发。请从以下提取路径选择正确的 SDK 文件：Win10 或 Win81。
internetClient 功能
确保您的项目在 package.appxmanifest 文件中具有 internetClient 功能。
Visual Studio
- 双击“解决方案资源管理器”中的
appxmanifest。 - 选择“功能”
- 确认已勾选“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 来确定哪个广告位置触发了事件。
// Event handler for OnAdPlayableChanged event private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { // e.Placement - placement ID in string // Run asynchronously on the UI thread 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 中，我们统一使用“激励式”广告这一术语。
|
选项 |
默认值/类型 |
说明 |
|
|
AutoRotate DisplayOrientations |
注意：此选项仅适用于移动应用程序。 |
|
|
true 布尔值 |
设置广告开始时的声音状态。 如果为 true（默认），音频将遵循设备的音量和声音设定。 如果为 false，视频将静音播放，但用户可自行调节。 |
|
|
false 布尔值 |
如果为 true，用户可以使用返回按钮立即退出广告。 如果为 false（默认），用户在屏幕上显示“关闭”按钮之前无法使用“返回”按钮退出广告。 注意：此选项仅适用于移动应用程序。 |
|
|
null 字符串 |
在使用服务器到服务器回调进行验证时，将唯一用户 ID 传递至您的应用程序，以验证该用户因观看激励式广告所应获得的奖励。 注意：此设置仅适用于有奖励的广告位置。 |
|
|
“关闭此广告？” 字符串 |
设置跳过激励式广告时的确认对话窗口标题。 注意：此设置仅适用于有奖励的广告位置。 |
|
|
“确定要跳过此广告吗？您必须看完广告才能获得奖励。” 字符串 |
设置跳过激励式广告时的确认对话窗口正文。 注意：此设置仅适用于有奖励的广告位置。 |
|
|
“关闭”
字符串 |
设置跳过激励式广告时确认对话窗口中的“取消”按钮文字。 注意：此设置仅适用于有奖励的广告位置。 |
|
|
“继续” 字符串 |
设置跳过激励式广告时确认对话窗口中的“继续观看”按钮文字。 注意：如果不是激励式广告，则该设置不适用。 |
|
|
- |
已弃用 您可以从管理面板进行广告位置级别的奖励式配置。请参阅广告位置的设置和报告。 |
注意：Dynamic Template 与 Flex View 广告的 SoundEnabled 选项和激励式对话框可在管理面板上进行配置。编程配置仅适用于原有的广告。
显示“关闭”按钮
若要控制用户是否有权关闭广告，请在 Vungle 管理面板上使用应用程序高级设置中的强制观看选项。
GDPR 推荐实施方法说明
// To set the user’s consent status as opted in: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentAccepted); // To set the user’s consent status as opted out: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentDenied); // To find out what the user’s current consent status is: // This will return null if the GDPR Consent status has not been set // Otherwise, it will return VungleConsentStatus.VungleConsentAccepted or // VungleConsentStatus.VungleConsentDenied UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus(); 订阅事件处理程序
Windows SDK 提供了一些您可以编程处理的事件。您可以使用这些事件处理程序控制应用程序的某些功能，例如暂停/继续播放背景音乐。
UI 线程注释
事件侦听器在后台线程中执行，因此任何由事件侦听器导致的 UI 交互或更新在执行之前都必须传递到主 UI 线程。以下是一种实现方法：
await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ // This block will be executed in the UI thread
} ); VungleAd 事件处理程序
|
事件处理程序 |
说明 |
|
|
在 SDK 完成初始化后立即调用。您可以检查是否有从之前会话下载的广告或为广告位置加载广告。 |
|
|
通知某一广告位置的广告可用性变化情况。在为广告位置加载广告后，等待此事件处理程序在广告可用时执行操作。 |
|
|
在播放广告前调用。您可以执行相关操作，例如暂停背景音乐。 |
|
|
在用户关闭结束卡、控制转回至您的应用程序时调用。如果 |
|
|
在 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();