Vungle SDK v. 6 - Unity 入门指南

目录

 

开始之前

  • Vungle Unity (iOS) 插件支持:
    • iOS 8
    • Unity 4 和 Unity 5.4.1 或更高版本
    • Vungle SDK 需要将 WebKit.framework 框架与您的项目进行链接,因此,您在面向 IOS 7 进行开发时,必须将此框架设为“可选”。为此,请在“项目导航”中单击相应的项目,然后前往“通用链接的框架和库”。选择 WebKit.framework,并将“状态”设为“可选”。

  • Vungle Unity (Android) 插件:
    • 需要 Android Java 1.7
    • 支持 Unity 4 和 Unity 5.3.2 信更高版本

  • Vungle Unity (Windows) 插件:
    • Windows(Universal 8.1 或 Phone 8.1)支持 Unity 4 和 Unity 5.3.2+
    • Windows 10 UWP 支持 Unity 5.3.2+
    • 在继续执行本文的剩余操作之前,请先按照“为 Unity 准备 Vungle Windows SDK v.2.0+ 环境”中的说明进行操作,然后返回此处,然后完成剩余的操作步骤。

  • 下载示例应用程序:https://github.com/Vungle/Unity-Plugin/tree/sdk6

 

步骤 1:使用 Vungle Unity 插件设置 Unity 项目

将 Vungle Unity 插件添加到 Unity 项目中

在 Unity 中打开您的项目,双击下载的 VunglePlugin.unitypackage 文件以将 Vungle Unity 插件添加到您的应用程序。当“导入 Unity 程序包”窗口打开时,点击“全部”即可选择全部,然后导入。

 

在构建设置中选择面向的正确平台。

为避免后续步骤中的编译错误,请确保项目的“构建设置”(cmd + Shift + B) 选择面向的是 iOS 或 Android 平台。

Amazon 应用商店

Vungle Android SDK 支持 Amazon OS 5.4 及更高版本。您可以将 Android APK 提交至 Amazon 应用商店(须额外进行 Unity Amazon 应用商店配置)。Unity 操作说明详见:https://docs.unity3d.com/Manual/UnityIAPAmazonConfiguration.html

Google Play Services

在项目中添加 Google Play Services 之后,Vungle 即可为终端用户提供更加个性化的广告体验,但这并非必需要求。我们建议使用 11.0.1 或更高版本。

如要添加 Google Play Services,我们建议您查阅开发人员门户上的“Google 设置指南”,网址为 http://developer.android.com/google/play-services/setup.html#Setup。在您的应用程序中,请确保设备已安装版本足够新的 Google Play Services。Vungle SDK 随意使用来自 Google Play Services 的广告位置和广告 API。

  • android.gms:play-services-location:11.0.1
  • android.gms:play-services-ads:11.0.1
  • 对于 Google Play Services 7.8.0 及以下版本:保留支持库
  • 对于 Google Play Services 8.4.0 及以上版本:不需要支持库

我们已成功编译了独立的 SDK 以便与以下 Google Play Services 版本一起编译:7.8.0、8.4.0、9.8.0、10.2.4 和 11.0.1。

添加 Google Play Services 后,再将以下权限添加到 AndroidManifest.xml 中。Vungle 会使用这些信息为用户定制最适合的广告。

  • <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  • <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

 

添加硬件加速(仅限 Android)

如果将目标 API 级别设置为 14 或以上,则默认启用硬件加速。必须启用此选项才能使 SDK 正确显示 Dynamic Template 和 Native Flex 广告。请确保此选项在您的项目中未设置为“false”:

示例代码:

<application android:hardwareAccelerated="true" ...>

 

步骤 2:添加代码

在本演练中,我们初始化了附属于主“游戏对象”的脚本中的所有 Vungle 相关代码。您可以从任何您认为合适的脚本中调用 Vungle Unity 插件

 

初始化 SDK

注意:系统会自动为每个应用程序创建一个默认广告位置。无论是否打算利用该广告位置功能,您都必须在此初始化步骤中提供其广告位置参考 ID。如果创建了多个广告位置,请提供所有参考 ID。

启动应用程序后,应立即初始化 SDK,以便为 SDK 提供足够时间对自动缓存的广告位置进行广告缓存。要初始化 SDK,您需要:

  • 所需支持的所有平台的所有应用程序 ID
  • 想要在应用程序(面向所有平台)中使用的所有广告位置的参考 ID(包括活动的和非活动的)。

您可以在 Vungle 管理面板中找到这些 ID(请参阅“广告位置的设置和报告”)。

示例代码:

public class VungleScript : MonoBehaviour { string appID = "";
string iosAppID = "ios_app_id";
string androidAppID = "android_app_id";
string windowsAppID = "windows_app_id"; #if UNITY_IPHONE appID = iosAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "ios_placement_id_1", false }, { "ios_placement_id_2", false }, { "ios_placement_id_3", false } }; #elif UNITY_ANDROID appID = androidAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "android_placement_id_1", false }, { "android_placement_id_2", false }, { "android_placement_id_3", false } }; #elif UNITY_WSA_10_0 || UNITY_WINRT_8_1 || UNITY_METRO appID = windowsAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "windows_placement_id_1", false }, { "windows_placement_id_2", false }, { "windows_placement_id_3", false } }; #endif string[] array = new string[placements.Keys.Count]; placements.Keys.CopyTo(array, 0); Vungle.init(appID, array);
}

当 SDK 成功完成初始化后,会调用以下事件:

公用静态事件 Action onInitializeEvent;

请参阅本文的“事件处理”部分。

Vungle SDK 初始化之后,它会自动对您在 Vungle 管理面板中选定为“自动缓存”的广告位置请求广告。我们建议选择观看次数最多的广告位置用于自动缓存。

广告被成功缓存后,即会调用其广告位置参考 ID 与您选定的“自动缓存”广告位置相匹配的 adPlayableEvent 事件。(请参阅本文的“检查广告位置的广告可用性”部分。)

 

为广告位置加载广告

对于非自动缓存的广告位置,应调用 loadAd 方法来加载广告。

public static void loadAd(string placementID)

请确保使用的是与正确平台链接的 placementID

示例代码:

string placementID; #if UNITY_IPHONE placementID = "ios_placement_id"; #elif UNITY_ANDROID placementID = "android_placement_id"; #elif UNITY_WSA_10_0 || UNITY_WINRT_8_1 || UNITY_METRO placementID = "windows_placement_id"; #endif Vungle.loadAd(placementID);

 

检查广告位置的广告可用性

当 SDK 完成广告位置的广告缓存后,会调用以下事件:

public static event Action<string, bool> adPlayableEvent;

示例代码:

Vungle.adPlayableEvent += (placementID, adPlayable) => { if(placementID == "ios_placement_id") { playButtonPlacement1.enabled = adPlayable; } };

注意:对于自动缓存的广告位置,此事件仅在有可用广告时才会被调用。SDK 将会一直为自动缓存的广告位置请求广告。对于其他广告位置,此事件在“加载失败”(adPlayable 此时会返回“false”)时也会被调用。

您还可以通过以下方法来检查广告位置的广告可用性:

public static bool isAdvertAvailable(string placementID);

播放广告

重要事项:请勿在上述 adPlayableEvent 函数返回“true”之前播放广告。如果尝试在 adPlayableEvent 函数返回“true”之前播放广告,此时会因为广告尚在加载而影响用户体验。如果要部署到 Android 上,则应使用 isAdvertAvailable() 返回的值来确保有可用的广告(没有可用的广告时,adPlayableEvent 不会返回 false)。

当某广告位置有可用的广告时,您可以使用以下方法来播放广告:

public static void playAd(string placementID);

示例代码:

Vungle.playAd (placementID);

 

事件处理

您可以设置事件处理器,用于处理广告展示周围的所有 5 个 Vungle SDK 事件。

  • 当 SDK 开始播放视频广告时,会触发以下事件。此时是暂停游戏、声效和动画等内容的最佳时机。
    public static event Action onAdStartedEvent;
  • 当 SDK 关闭广告时,会触发以下事件。此时是奖励用户并恢复游戏、声效和动画等内容的最佳时机。
    public static event Action<string, AdFinishedEventArgs> onAdFinishedEvent;

    AdFinishedEventArgs 类包含以下属性,用于检查广告播放效果:
    public class AdFinishedEventArgs : EventArgs { //代表一个布尔值,即用户是否点击了下载按钮。 public bool WasCallToActionClicked{ get; set;} //代表一个布尔值,即视频是否可以被认为得到了完整播放。 public bool IsCompletedView{ get; set;} }
  • 当 SDK 更改了广告可用性状态时,会触发以下事件。isAdPlayable 布尔值表示存在新的可播放 placementID
    public static event Action<string, bool> adPlayableEvent;
    请参阅本文的“检查广告位置的广告可用性”部分,了解更多详情。

  • 当 SDK 成功完成初始化时,会触发以下事件。
    公用静态事件 Action onInitializeEvent;

示例代码:

void initializeEventHandlers() { Vungle.onAdStartedEvent += (placementID) => { DebugLog ("Ad " + placementID + " is starting! Pause your game animation or sound here."); }; Vungle.onAdFinishedEvent += (placementID, args) => { DebugLog ("Ad finished - placementID " + placementID + ", was call to action clicked:" + args.WasCallToActionClicked + ", is completed view:" + args.IsCompletedView); }; Vungle.adPlayableEvent += (placementID, adPlayable) => { DebugLog ("Ad's playable state has been changed! placementID " + placementID + ". Now: " + adPlayable); }; Vungle.onInitializeEvent += () => { adInited = true; DebugLog ("SDK initialized"); }; }

 

OnPause 和 OnResume 功能

添加 onPauseonResume 等功能的代码,允许因某个应用程序进入后台运行而被暂停的广告恢复播放。

void OnApplicationPause(bool pauseStatus) { if (pauseStatus) { Vungle.onPause(); } else { Vungle.onResume(); } }

 

自定义选项

playAd 方法可以接受一个选项词典来自定义广告播放体验。

public static void playAd(Dictionary<string,object> options, string placementID);

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

选项字典接受以下键:

说明

orientation

设置广告的方向。

  • 对于 iOS,使用 VungleAdOrientation
    public enum VungleAdOrientation { Portrait = 1, LandscapeLeft = 2, LandscapeRight = 3, PortraitUpsideDown = 4, Landscape = 5, All = 6, AllButUpsideDown = 7 }
  • 对于 Android,将 matchVideo 设为 true,并将 autoRotate 设为 false

userTag

用户密钥字符串:来回传递用于识别 S2S 调用中的用户(如有)。

alertTitle

标题字符串:用于在用户过早关闭激励式广告体验时所显示的警告对话框标题。

alertText

正文文本的字符串:用于在用户过早关闭激励式广告体验时所显示的警告对话框正文。

closeText

“关闭”按钮文本的字符串标题:用于在用户过早关闭激励式广告体验时所显示的警告对话框按钮。

continueText

“关闭”按钮文本的字符串标题:用于在用户过早关闭激励式广告体验时所显示的警告对话框按钮。

immersive

布尔值:用于设置沉浸模式(强制隐藏导航栏和状态栏)。(仅限 Android)

flexCloseSec

整数:用于确定 Flex View 广告自动关闭的播放秒数。此设置仅影响 Flex View 广告。(仅适用于 iOS)

 

GDPR:推荐实施方法

《通用数据保护条例》(GDPR) 将于 5 月 25 日在欧盟生效。为了遵守 GDPR,开发者有以下两种选择。

  • 选项 1(推荐):发布商从用户级别控制 GDPR 的同意流程,然后将用户的选择传达给 Vungle。为此,开发人员可以使用自己的机制来收集用户的同意信息,然后使用 Vungle API 更新或查询用户的同意状态。若需了解详细信息,请参阅“GDPR 推荐实施方法说明”部分。

  • 选项 2:允许 Vungle 处理相关需求。Vungle 在向欧洲用户播放广告之前会显示征求同意的对话框,并记住用户的同意或拒绝选择,以用于后续的广告。

GDPR 推荐实施方法说明

要使用 Vungle API 来更新或查询用户同意状态(参见选项 1 中的推荐),请使用 Vungle.Consent 枚举器,并将当前值设置为以下两个函数。

// The Consent enum is used to represent the user's current GDPR opt-in status public enum Consent { Undefined = 0, Accepted = 1, Denied = 2 } // Sets the user's consent status void updateConsentStatus(Vungle.Consent consent); // Gets the user's consent status Vungle.Consent getConsentStatus(); 

 

Flex View 广告

对于 iOS

要通过编程方式关闭 Flex View 广告,请使用 closeAd 函数:

Vungle.closeAd(placementID);

此函数不适用于 Android。

对于 Android

Flex View 在 Unity Android 平台上的工作方式与 Unity iOS 或原生 Android 平台有所不同。由于 Unity 处理活动的方式受到限制,Flex View 不允许用户在显示 Flex View 广告时与基础游戏进行交互。在 Flex View 广告中,当顶层活动发生时,底层活动将被暂停。如果用户在 Flex View 广告播放时暂时离开了应用程序,稍后又返回到该应用程序,则该广告仍会显示,但后台游戏将显示为黑色。发生这种情况是因为在 Flex View 广告结束之前,基础活动将一直被暂停。

因此,避免在 Unity Android 上使用 Flex View 广告。

对于 Windows

Windows 系统不支持 Flex View 广告。

 

Flex Feed 广告

通过 Unity 插件进行 Vungle 集成时,不支持 Flex View 广告。

这篇文章有帮助吗?
1 人中有 1 人觉得有帮助