Vungle SDK v. 6 - Adobe AIR 入门指南

请遵循这些说明将 Vungle Adobe Air 插件快速集成到基本示例应用程序中。这里引用的源代码可以在我们的公共 GitHub 存储库中获得。

目录

开始之前

  • Vungle 扩展必须安装 Adobe AIR SDK 4.0 或更高版本。有关在 Flash Builder 或 Flash Professional 中更新 AIR SDK 的说明,请参阅“补充说明”部分。

  • 如果是 Android 平台,则 Vungle AIR 扩展需要在开发系统中安装 JDK 6 或 JDK 7(具体取决于所用的 Flash 版本)。使用 Android 3.0(Honeycomb - API 版本 11)或更高版本才能确保应用程序正常运行

  • 您可参阅ActionScript 3 类文档

  • 审核示例应用程序类的 example/VungleExample.as。(如果您是 Flash Professional 用户,并且不知道如何使用文档类,请查阅本指南结尾的“在 Animate 或 Flash Professional CS6 中使用 VungleExample.as 文档类?”)
  • 硬件加速

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

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

 

GDPR:推荐实施方法

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

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

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

步骤 1:添加扩展库

首先创建新的 AIR for mobile 项目并添加本机扩展。您需要添加两个或三个 .ane 文件:

  • com.vungle.extensions.Vungle.ane
  • com.vungle.extensions.android.AndroidSupportLib.ane
  • com.vungle.extensions.android.GooglePlayServices.ane(如果面向 Android 平台,则可能还需要在项目中添加 Google Play Services 库。但由于其他许多扩展程序已经包含此库,项目中可能已有这个库了)。

对于 Animate 和 Flash Professional CS6 或更高版本

  1. 创建一个新的 AIR for Android 或 AIR for iOS 项目。
  2. 选择“文件 → 发布设置...”
  3. 选择“脚本”旁边的扳手图标进入“ActionScript 设置”。
  4. “库路径”选项卡中,单击“浏览本机扩展 (ANE) 文件”,并选择 vungle.extensions.Vungle.ane 文件。然后单击“确定”
  5. 选择“目标”旁边的扳手图标进入“播放器设置”。
  6. 如果面向 Android 平台:在“权限”选项卡中,分别启用 'INTERNET''WRITE_EXTERNAL_STORAGE''ACCESS_NETWORK_STATE'
  7. 选择“手动管理为本应用程序的权限和清单补充”选项,并单击“确定”
  8. 重复执行步骤 1-7,这次在步骤 4 中选择 com.vungle.extensions.android.AndroidSupportLib.ane
  9. 如果面向 Android 平台并且此库不存在,请再次执行上述步骤,这次在步骤 4 中选择 com.vungle.extensions.android.GooglePlayServices.ane 文件。

对于 Flash Builder 4.6 或更高版本

  1. “项目属性”中的“Actionscript 构建路径”下,选择本机扩展
  2. 选择“添加 ANE...”并导航到 vungle.extensions.Vungle.ane 文件。
  3. 选择“Actionscript 构建打包 → Google Android”
  4. “本机扩展”选项卡中,选择扩展旁边的“打包”选项。
  5. 重复执行步骤 1-2,这次在步骤 2 中选择 com.vungle.extensions.android.AndroidSupportLib.ane
  6. 如果面向 iOS,对“Apple iOS”目标重复步骤 3 和 4。

步骤 2:升级应用程序描述符

为确保 Vungle 正常运行,需要针对您的应用程序修改相应的 XML 文件。对 IDE 创建的 XML 文件进行以下更改。

注意:如果是 Flash Professional 用户,确保遵循了上述添加扩展库的步骤(对于 Animate 和 Flash Professional CS6 或更高版本);否则,当您进行修改时,Flash 可能撤销您的修改。

  1. 在应用程序描述符文件中将 AIR SDK 设置为 4.0(或更高版本):
    <application xmlns="http://ns.adobe.com/air/application/4.0">
  2. 在描述符中添加该扩展的链接:
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.AndroidSupportLib</extensionID>
    </extensions>
  3. 如果面向 Android:您可能还需要添加 Google Play Services 扩展。应在此添加其扩展 ID。
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.AndroidSupportLib</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    </extensions>

对于面向 Android 的 AIR 应用程序

如果面向 Android,请将 android XML 元素中的 Android 清单补充更新为:

  • 添加 INTERNETWRITE_EXTERNAL_STORAGEACCESS_NETWORK_STATE 权限
  • 添加 VideoFullScreenAdActivityMraidFullScreenAdActivity, MraidFullScreenAdActivity 活动定义
  • 添加 google play services 版本元数据标记:
     <android>

    <manifestAdditions><![CDATA[

    <manifest android:installLocation="auto">

    <!--Required Permissions-->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="18" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <!--Optional Permissions-->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <application
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:theme="@style/AppTheme"
    android:networkSecurityConfig="@xml/network_security_config" >
    <activity android:name=".MainActivity">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <!-- Google Play Services -->
    <meta-data android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />
    <!-- Vungle -->
    <activity
    android:name="com.vungle.warren.ui.VungleActivity"
    android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
    android:launchMode="singleTop"
    android:theme="@android:style/Theme.Translucent.NoTitleBar" />
    <!-- android-job -->
    <service
    android:name="com.evernote.android.job.v21.PlatformJobService"
    android:exported="false"
    android:permission="android.permission.BIND_JOB_SERVICE" />
    <service
    android:name="com.evernote.android.job.v14.PlatformAlarmService"
    android:exported="false"
    android:permission="android.permission.BIND_JOB_SERVICE" />
    <service
    android:name="com.evernote.android.job.v14.PlatformAlarmServiceExact"
    android:exported="false" />
    <receiver
    android:name="com.evernote.android.job.v14.PlatformAlarmReceiver"
    android:exported="false" >
    <intent-filter>
    <!-- Keep the filter for legacy intents -->
    <action android:name="com.evernote.android.job.v14.RUN_JOB" />
    <action android:name="net.vrallev.android.job.v14.RUN_JOB" />
    </intent-filter>
    </receiver>
    <receiver
    android:name="com.evernote.android.job.JobBootReceiver"
    android:exported="false" >
    <intent-filter>
    <action android:name="android.intent.action.BOOT_COMPLETED" />
    <action android:name="android.intent.action.QUICKBOOT_POWERON" />
    <action android:name="com.htc.intent.action.QUICKBOOT_POWERON" />
    <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
    </intent-filter>
    </receiver>
    <service
    android:name="com.evernote.android.job.gcm.PlatformGcmService"
    android:enabled="false"
    android:exported="true"
    android:permission="com.google.android.gms.permission.BIND_NETWORK_TASK_SERVICE" >
    <intent-filter>
    <action android:name="com.google.android.gms.gcm.ACTION_TASK_READY" />
    </intent-filter>
    </service>
    <service
    android:name="com.evernote.android.job.JobRescheduleService"
    android:exported="false"
    android:permission="android.permission.BIND_JOB_SERVICE" />
    </application>

    </manifest>
    ]]></manifestAdditions>

     </android>

步骤 3:集成 Vungle API

只需几行 ActionScript,即可将 Vungle API 添加到您的应用程序。

初始化 Vungle 扩展

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

当您的应用程序启动时,初始化 API。

  • 如果使用纯 ActionScript,请在文档类的构造函数中执行此操作。
  • 如果使用 Flex,请在主类的 initialize() 事件中调用此步骤。
  • 如果使用 Flash 中的时间轴代码,请在 Frame 1 上执行此操作。
  1. 导入 API 类:
    导入 com.vungle.extensions.*; 导入 com.vungle.extensions.events.*;
  2. 初始化 API,方法是:调用 create(),然后从 Vungle 管理面板传递一个应用程序 ID 字符串以及一个包含该应用程序广告位置参考 ID 的字符串数组。如果同一个项目需要同时面向 iOS 和 Android 平台,请按平台分别向 create() 方法提供不同的应用程序 ID 及其广告位置数组。

    在 try/catch 中对 Vungle.create() 调用进行打包,因为 Vungle 可能会在创建过程中报错(例如,如果在台式机上运行该扩展程序,系统就会报错):
    try { // 使用您的应用程序 ID 来初始化 Vungle.create("your_vungle_id", [“placement1”, “placement2”, “placement3”]); } catch (error:Error) { // 无法创建扩展。您在运行 iOS/Android 之外的程序吗? }

加载广告位置的广告

如要播放某个广告位置的广告,必须先为该广告位置加载广告。请注意,自动缓存的广告位置不需要您调用此方法。SDK 将会自动为自动缓存的广告位置加载广告。

Vungle.vungle.loadAd(“non_auto_cached_placement”);

播放广告位置的广告

通过事件侦听器可以了解广告何时准备好播放。当广告位置就绪时,即可播放广告了。

If (Vungle.vungle.isAdAvailable(“placement_id”)) { Vungle.vungle.playAd(“placement_id”); }

添加事件侦听器

Vungle 扩展会分派六个事件:VungleEvent.AD_PLAYABLEVungleEvent.AD_STARTEDVungleEvent.AD_FINISHEDVungleEvent.AD_FAILEDVungleEvent.AD_INITVungleEvent.AD_LOG

  1. 当广告播放就绪时,将分派 AD_PLAYABLE
    Vungle.vungle.addEventListener(VungleEvent.AD_PLAYABLE, onAdPlayable); function onAdPlayable(e:VungleEvent):void { if (e.isAdPlayable) { trace(“ad is playable for placement: “ + e.placement); Vungle.vungle.playAd(e.placement); } else { trace(“ad not playable for placement: “ + e.placement); } }
  2. 当广告播放和结束时,将分别分派 AD_STARTEDAD_FINISHED 事件:
    Vungle.vungle.addEventListener(VungleEvent.AD_STARTED, onAdStarted); Vungle.vungle.addEventListener(VungleEvent.AD_FINISHED, onAdFinished); function onAdStarted(e:VungleEvent):void { trace("ad displayed for placement: " + e.placement); } function onAdFinished(e:VungleEvent):void { trace("ad dismissed for placement: “ + e.placement + “, CTA = " + e.wasCallToActionClicked); if (e.wasSuccessfulView) { trace("counts a completed view - present reward."); } }
  3. 当 Vungle SDK 完成初始化时,将分派 AD_INIT
    function onAdInit(e:VungleEvent):void { trace(“Vungle SDK is initialized: “ + e.isInitialized”); }
  4. 当 Vungle SDK 发送日志消息时,将分派 AD_LOG。您可以使用它进行调试。日志记录功能仅对 Vungle SDK iOS 可用,所以此事件特定于平台。
    Vungle.vungle.setLoggingEnabled(true); Vungle.vungle.addEventListener(VungleEvent.AD_LOG, onAdLog); private function onAdLog(e:VungleEvent):void { log("ad log: " + e.message); }

更多选项

如前所述,您在调用 playAd() 方法时可以传递含有配置选项的对象。

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

以下是 VungleAdConfig 中的可用属性:

选项

说明

orientation

VungleOrientation

Android

VungleOrientation.AUTO_ROTATE

VungleOrientation.ANDROID_MATCH_VIDEO

iOS

VungleOrientation.IOS_LANDSCAPE

VungleOrientation.IOS_PORTRAIT

soundEnabled

布尔值

如果为 true(默认),则播放视频广告时将启用声音(取决于设备的声音设置)。如果为 false,播放视频时为静音。请注意,用户可以在播放过程中调成静音或取消静音。

backButtonImmediatelyEnabled

布尔值

仅限 Android,如果设为 true,则用户可以使用返回按钮立即退出广告。如果设为 false(默认),用户在屏幕上显示“关闭”按钮之前无法使用“返回”按钮退出广告。

immersiveMode

布尔值

仅限 Android,如果设为 true,它将在 KitKat+ 设备上启用沉浸模式。默认设置为 false

incentivizedUserId

字符串

您可以设置一个可传递至应用程序的唯一用户 ID,用于验证该用户因观看激励式广告所应获得的奖励。

flexViewCloseTimeInSec

整数

使用此选项可让 Flex View 广告在指定秒数后自动消失。
此功能仅适用于 Flex View 广告。

incentivizedCancelDialogTitle

字符串

您可以自定义一条提示信息,当用户试图关闭未播放完的视频时,屏幕上会显示这条信息。

 

注意:此选项仅适用于标准的 Vungle 广告,不支持 Dynamic Template 广告。适用于 Dynamic Template 广告的选项可在管理面板中指定,并且具有相同的选项。

incentivizedCancelDialogBodyText

incentivizedCancelDialogCloseButtonText

incentivizedCancelDialogKeepWatchingButtonText

示例代码:

var adConfig:VungleAdConfig = new VungleAdConfig(); adConfig.orientation = VungleOrientation.ANDROID_MATCH_VIDEO | VungleOrientation.IOS_LANDSCAPE; adConfig.soundEnabled = false; android: { adConfig.backButtonImmediatelyEnabled = true; adConfig.immersiveMode = true; }; adConfig.incentivizedUserId = "vungle_test_user"; adConfig.incentivizedCancelDialogBodyText = "body_text"; adConfig.incentivizedCancelDialogCloseButtonText = "close_button_text"; adConfig.incentivizedCancelDialogKeepWatchingButtonText = "continue_button_text"; adConfig.incentivizedCancelDialogTitle = "title_text"; Vungle.vungle.playAd(placement, adConfig);

全局默认值

您可以使用全局配置对象来设置这些选项的默认值:

// set any configuration options you like VungleAdConfig.globalConfig.orientation = VungleOrientation.ANDROID_MATCH_VIDEO; VungleAdConfig.globalConfig.soundEnabled = false;

以后创建任何新的 VungleAdConfig 对象时将采用这些值作为默认设置。playAd() 如无选项则也使用全局配置。

注意:如果应用程序处于测试模式,您将无法下载广告中的任何应用程序。此外,“管理面板”也不会报告展示次数。这是因为测试广告仅用于验证您的 SDK 集成是否正确。此功能在您的应用程序以活动模式上线后即可使用。

Flex View 广告

要通过编程方式关闭 Flex View 广告,请在广告启动后调用 closeFlexViewAd 函数:

Vungle.vungle.closeFlexViewAd(placement);

此函数仅适用于 Flex View 广告和 Vungle SDK iOS 平台。

 

补充说明

GDPR 推荐实施方法说明

要使用 Vungle API 来更新或查询用户同意状态(参见“GDPR:推荐实施方法”选项 1 中的推荐),请使用以下函数:

更新同意状态

Vungle.vungle.updateConsentStatus(VungleConsent.ENUMSTATE);

可能的状态:

已接受 - VungleConsent.OPTED_IN // 1

已拒绝 - VungleConsent.OPTED_OUT // 0

 

获取当前的同意状态

//Returns a VungleConsent enum

var status:int = Vungle.vungle.getConsentStatus();

 

在 Animate 或 Flash Professional CS6 中使用 VungleExample.as 文档类

  1. 首先,按照本集成指南第 1-3 节的说明创建应用程序并添加相关扩展。
  2. 将其复制粘贴到您的 .fla 文件所在的同一个文件夹内。请勿将其内容复制粘贴到时间轴上。
  3. 请将第 20 行中的应用程序 ID 和广告位置 ID 修改为您自己的 Vungle ID。
  4. 在 Flash 属性的“文档类”下,输入 VungleExample 并单击“确定”
  5. 构建并安装应用程序。

在 Flash Professional CS6 中安装新版 AIR SDK(4.0 或更高)

请沿此链接查找最新版本 AIR SDK。如果已安装 AIR 4.0 或更高版本,可以跳过此步骤。否则,请遵循以下说明操作:

  1. 将 AIR 4.0 或更高版本的 SDK 文件包解压到硬盘上。
  2. 启动 Flash Professional CS6。
  3. 选择“帮助 → 管理 AIR SDK...”
  4. 单击“+”(加号)按钮并前往已解压的 AIR SDK 的所在位置。
  5. 单击“确定”
  6. 选择“文件 → 发布设置”
  7. “目标”下拉菜单中选择最新的 AIR SDK iOS。

在 Flash Builder 中安装新版 AIR SDK(4.0 或更高)

请沿此链接查找最新版本 AIR SDK。如果已安装 AIR 4.0 或更高版本,可以跳过此步骤。您还可以使用 Adobe 最新的 Flash Builder AIR SDK 更新说明

解决“Adobe Animate 无效输入”错误

如果收到下图所示的错误,请参阅此文章

image2.png

这篇文章有帮助吗?

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!