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 广告。

还有其它问题?提交请求

评论