Vungle - Windows SDK v.2.0+ 入门

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

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

目录

开始之前

  • 本指南适用于 Vungle Windows SDK 2.0 及更高版本。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 添加到您的项目

  1. 从 Vungle 仪表板下载 Vungle Windows SDK
  2. 解压存档文件。
  3. 在 Visual Studio 中,使用适合您应用程序和编程语言的模板创建一个新项目。
  4. 在您下载的 Vungle Windows SDK 文件中为您的项目添加引用。
  5. 请确保您的项目在 package.appxmanifest 文件中有 internetClient 功能,如下所示:
    <Capabilities>
    ...
    <Capability Name="internetClient" />
    ...
    </Capabilities>
  6. 导入 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 对象实例中的可用属性:

选项

默认值/
类型

说明

Orientation

AutoRotate

DisplayOrientations

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

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

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

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

SoundEnabled

true

bool

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

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

如果为 false,视频开始时为静音,但用户可自行调节。

BackButtonImmediatelyEnabled

false

bool

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

如果为 false(默认),在屏幕上的关闭按钮显示之前用户不可以使用返回按钮退出广告。

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

UserId

null

字符串

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

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

IncentivizedDialogTitle

“关闭此广告?”

字符串

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

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

IncentivizedDialogBody

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

字符串

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

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

IncentivizedDialogCloseButton

“关闭”

 

字符串

设置跳过奖励广告时确认对话窗口的 'cancel' 按钮。

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

IncentivizedDialogContinueButton

“继续”

字符串

设置跳过奖励广告时确认对话窗口的 'keep watching' 按钮。

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

Incentivized

-

已弃用

您可以从仪表板在广告位置级别设置奖励配置。请参阅广告位置的设置和报告


注意:
SoundEnabled 的选项以及动态模板广告和 Flex 视图广告的奖励对话可以通过仪表板进行配置。程序化配置只适用于旧广告。

显示“关闭”按钮

若要控制用户是否有关闭广告的选项,请使用 Vungle 仪表板上的应用高级设置中的强制观看选项。

订阅事件处理程序

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

UI 线程注释

事件侦听器在后台线程中执行,因此任何用户界面交互或事件侦听器产生的更新在执行之前都必须传递到主用户界面线程。以下为一种方法:

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ //此块将在 UI 线程中执行
} );

VungleAd 事件处理程序

事件处理程序

说明

OnInitCompleted

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

OnAdPlayableChanged

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

OnAdStart

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

OnAdEnd

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

Diagnostic

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

示例代码:

//注册事件处理程序
sdkInstance.OnInitCompleted     += SdkInstance_OnInitCompleted;
sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;
sdkInstance.OnAdStart           += SdkInstance_OnAdStart;
sdkInstance.OnAdEnd             += SdkInstance_OnAdEnd;
sdkInstance.Diagnostic          += SdkInstance_Diagnostic;

...

// OnInitCompleted
//   e.Initialized - 如果初始化成功为 true,失败为 false
//   e.ErrorMessage - 当 e.Initialized 为 false 时的失败原因
private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e)
{
  var placementsInfo = "OnInitCompleted: " + e.Initialized;
  //初始化成功
  if (e.Initialized == true)
  {
    //打印广告位置列表
    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)";
    }
  }
  //初始化失败
  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,否则为 false
//   e.Placement - 字符串中的广告位置 ID
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 应用 ID
//   e.Placement - 字符串中的广告位置 ID
private void SdkInstance_OnAdStart(object sender, AdEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement);
}

// OnAdEnd
//   e.Id - 字符串中的 Vungle 应用 ID
//   e.Placement - 字符串中的广告位置 ID
//   e.IsCompletedView- 观看视频内容 80% 或更多时为 true
//   e.CallToActionClicked - 用户点击了结束卡上的下载按钮时为 true
//   e.WatchedDuration - 已弃用
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);
}

//在 SDK 想要打印诊断日志时调用的事件处理程序
private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e)
{
  System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } //已弃用 - 改用 SdkInstance_OnAdEnd() private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }
还有其它问题?提交请求

评论