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

还有其它问题?提交请求

评论