Vungle - Adobe Air 入门指南

Adobe Air 扩展说明

开始之前:

  • Vungle 扩展需要 Adobe AIR SDK 4.0 或更高版本。 如需了解如何在 Flash Builder 或 Flash Professional 中升级 AIR SDK,请参阅本指南篇末“如何升级 AIR SDK?”。

  • 若搭配 Android 系统使用,Vungle AIR 要求在开发系统中事先安装 JDK 7。

  • 请参阅 ActionScript 3 Class Documentation

  • 应用程序类别示例见“example/VungleExample.as”。(如果您是 Flash Professional 用户并且不清楚如何使用 Document Class(文档类型),请见本指南篇末“如何使用 Flash CS6 中的 VungleExample Document Class?”。)

1.含扩展函数库

首先给移动项目创建一个新的 AIR 并添加本地扩展。

若目标为 Android:您还需给项目添加 Google Play Services 和/或 Android Support v4 函数库。许多其它扩展都包含此类函数库,所以您无需再添加。欲添加扩展,可重复下列步骤,但需使用 com.vungle.extensions.android.GooglePlayServices.ane 和/或 com.vungle.extensions.android.AndroidSupportLib.ane 替代 com.vungle.extensions.Vungle.ane。

若在 Flash Professional CS6 或更高版本当中:

  1. 给 Android 或 iOS 项目创建一个新的 AIR
  2. 选择File > Publish Settings...(文件 > 发布设置...)
  3. 选择“Script”(脚本)旁边用于“ActionScript Settings”(ActionScript 设置)的扳手图标
  4. 选择“Library Path”(库路径)标签
  5. 点击“Browse for Native Extension (ANE) File”(浏览本地扩展(ANE)文件)并选择 com.vungle.extensions.Vungle.ane 文件。按 OK
  6. 选择“Target”(目标)旁边用于“Player Settings”(播放器设置)的扳手图标
  7. 若目标为 Android:选择“Permissions”(权限)标签并启用“INTERNET”、“WRITE_EXTERNAL_STORAGE”和“ACCESS_NETWORK_STATE”
  8. 勾选“Manually manage permissions and manifest additions for this app”(手动管理权限并显示该应用程序的添加项)选项框
  9. 按 OK

若在 Flash Builder 4.6 或更高版本当中:

  1. 前往 Project Properties(项目属性)
  2. 选择Actionscript Build Path(Actionscript 创建路径)下的Native Extensions(本地扩展)
  3. 选择Add ANE...(添加 ANE...)并导航至 com.vungle.extensions.Vungle.ane 文件
  4. 选择Actionscript Build Packaging > Google Android(Actionscript 创建组件 > Google Android)
  5. 选择 Native Extensions(本地扩展)标签并点击扩展项旁边的“Package”(套件)选项框
  6. 若目标为 iOS,重复第 4、5 步操作 Apple iOS 目标

2.升级您的应用程序描述符

要让 Vungle 运行,必须更改应用程序的 XML 应用文件。按以下说明更改您 IDE 创建的 XML 文件(如果您是 Flash Professional 用户,请务必遵守上述关于“Include the Library in Flash Professional CS6 or Higher”(将函数库包括在 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>
    </extensions>
  3. 若目标为 Android:您可能需要写入 Google Play Services 和/或 Android Support Lib 扩展。并同时在此处添加扩展 ID。

    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    <extensionID>com.vungle.extensions.android.AndroidSupportLib</extensionID>
    </extensions>

若 AIR 应用程序以 Android 为目标

若目标为 Android,在 XML 元素中升级 Android Manifest Additions,写入 INTERNET、WRITE_EXTERNAL_STORAGE 和 ACCESS_NETWORK_STATE 权限;添加 FullScreenAdActivity 活动定义;添加 VungleService 服务;添加 google-play-services(谷歌市场服务)版本的 meta-data(元数据)标签:

<android> 
<manifestAdditions><![CDATA[ 
<manifest android:installLocation="auto"> 

  <uses-permission android:name="android.permission.INTERNET"/> 
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> 
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 

  <application>
    <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>

    <activity
      android:name="com.vungle.publisher.FullScreenAdActivity"
      android:configChanges="keyboardHidden|orientation|screenSize"
      android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
    />

    <service android:name="com.vungle.publisher.VungleService"
      android:exported="false"
    />
  </application> 
</manifest> 
]]></manifestAdditions>
</android>

3.集成 Vungle API

只需写入几条 ActionScript 指令便可将 Vungle API 添加到您的应用程序。

初始化 Vungle Extension

应用程序启动后初始化 API 。(若使用纯净版 ActionScript,请在 Document Class 的构造函数中操作。若使用 Flex,请在主类型的 initialize()事件中调用该功能。若使用 Flash 中的时间线代码,请在 Frame 1 中操作。)

  1. 导入 API 类型:

    import com.vungle.extensions.*; 
    import com.vungle.extensions.events.*;
  2. 初始化 API,方法如下:调用 Vungle.create(),并从 Vungle Dashboard 通过一组包含您应用程序 ID 的阵列。如果您的同一项目中既有 iOS 也有 Android 目标,请在阵列中写入 ID——先写 iOS ID,再写 Android ID。

    由于 Vungle 可能在创建过程中抛出错误(例如扩展在台式电脑上运行时出错),您应该在 try/catch 模块中打包调用 Vungle.create():

    try
    { 
      // initialize with your app id 
      Vungle.create(["your_vungle_id"]); 
    
      // -OR- initialize including both ios and android ids for multiplatform apps 
      // Vungle.create(["your_ios_vungle_id","your_android_vungle_id"]); 
    } catch (error:Error) {
      // could not create extension. Are you running on something besides iOS/Android?
    }

显示插入式广告

显示插入式广告需调用 playAd()。若需初查广告可否使用,请用 isAdAvailable() 功能:

if (Vungle.vungle.isAdAvailable())
{
    Vungle.vungle.playAd();
}

显示激励式广告

显示激励式广告需调用 displayIncentivizedAd()。若需初查广告可否使用,请用 isAdAvailable() 功能。该功能带两个可选参数:是否在广告上显示 Close(关闭)按钮,以及可选的用户识别字符串(用于搭配 Vungle 的服务器端 webhooks 使用,以便在用户完成访问后触发 HTTP GET):

if (Vungle.vungle.isAdAvailable())
{
    var config:VungleAdConfig = new VungleAdConfig();
    config.incentivized = true;
    Vungle.vungle.playAd(config);
}

为奖励参与者完成激励式访问,您需要部署 AD_VIEWED 事件侦听器,如下所示。

添加事件侦听器

Vungle Extension 会发送五个事件:VungleEvent.AD_PLAYABLE, VungleEvent.AD_STARTED, VungleEvent.AD_FINISHED, VungleEvent.AD_VIEWED 和 VungleEvent.AD_LOG。

  1. 广告做好播放准备时会发送 AD_PLAYABLE 
    Vungle.vungle.addEventListener(VungleEvent.AD_PLAYABLE, onAdPlayable);
    
    function onAdPlayable(e:VungleEvent):void
    {
        trace("ad playable");
    }
    
  2. 显示和隐藏广告时分别会发送 AD_STARTED 和 AD_FINISHED 事件:

    Vungle.vungle.addEventListener(VungleEvent.AD_STARTED, onAdStarted); 
    Vungle.vungle.addEventListener(VungleEvent.AD_FINISHED, onAdFinished); 
    
    function onAdStarted(e:VungleEvent):void 
    { 
      trace("ad displayed"); 
    } 
    
    function onAdFinished(e:VungleEvent):void
    { 
      trace("ad dismissed: " + e.wasCallToActionClicked);
    }
  3. 用户不再处于 Vungle 广告当中,并且观看了部分视频时,会触发 AD_VIEWED 事件。“watched”(已观看)属性是指用户所看视频的观看时长,按秒计。“length”(长度)属性是指视频的总时长。

    (该事件可能在部分情况下被调用,例如广告中含有前置式 HTML 内容,且用户选择在观看视频前退出广告。)

    对于激励式广告,Vungle 假定访问状态为已完成访问达到视频的 80%:

    Vungle.vungle.addEventListener(VungleEvent.AD_VIEWED, onAdViewed); 
    
    function onAdViewed(e:VungleEvent):void 
    { 
      trace("watched"+e.watched+" of "+e.length+" second video."); 
      var percentComplete:Number=e.watched/e.length; 
      if(percentComplete>0.80) 
      { 
        trace("counts a completed view- present reward."); 
      } 
    }
  4. Vungle SDK 发出日志消息时会发送 AD_LOG。您可借此来排错。只有 iOS 版 Vungle SDK 会记录日志,所以该事件因平台而异。

    
    Vungle.vungle.setLoggingEnabled(true);
    Vungle.vungle.addEventListener(VungleEvent.AD_LOG, onAdLog);
    
    private function onAdLog(e:VungleEvent):void
    {
        log("ad log: " + e.message);
    }
    

切换自动转向

您可以使用 setAutoRotationEnabled() 功能来切换视频是否自动转向用户的设备:

Vungle.vungle.setAutoRotation(true);

更多选项

如前所述,在调用 playAd() 功能时您可以用配置选项传递某个对象。VungleAdConfig 中有若干属性可选:

orientation

用该属性您可以指定广告的发布方向。Android 和 iOS 的标记集不同,详见VungleOrientation分类。标记可结合按位运算的 OR(或)运算符:

config.orientation = VungleOrientation.ANDROID_AUTOROTATE | VungleOrientation.IOS_PORTRAIT;

soundEnabled

用该属性您可以切换广告是放音还是静音。

backButtonImmediatelyEnabled

该选项仅限 Android 使用。若为 true(真),此时用户可使用返回键立即退出广告。若为 false(假),在屏幕显示关闭按钮之前用户不能用返回键退出广告。

immersiveMode

该选项仅限 Android 使用。可启用或禁用 KitKat+ 设备的全盘模式

incentivized

设置激励模式。若为 true(真),用户在跳过广告时会看到一个确认对话框。

incentivizedUserId

单个的用户 ID 会传送到您的应用程序,以核实用户是否可以因观看激励式广告而获得奖励。

incentivizedCancelDialogTitle, incentivizedCancelDialogBodyText, incentivizedCancelDialogCloseButtonText, incentivizedCancelDialogKeepWatchingButtonText

上述选项可供您自定义跳过激励式广告时弹出的确认对话框。

extra1 … extra8

您可用此跟踪年龄组、性别等统计数据。

placement

An optional ad placement name for enhanced data categorization when requesting data through the Vungle Reporting API.

largeButtons

该选项仅限 iOS 使用。若设置为 true(真),那么屏幕显示的按钮尺寸会较大。

 

Global defaults

您可使用全局默认配置对象来设置相关选项的默认值:


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

此后每个新建的 VungleAdConfig 对象都会带默认值。不带选项的 playAd() 亦可使用全局配置。

不建议使用的功能

从 v2.4.0 版起不建议使用以下功能:


Vungle.vungle.displayAd(showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.displayIncentivizedAd(name:String, showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.setSoundEnabled(enabled:Boolean):void;
Vungle.vungle.setBackButtonEnabled(backEnabled:Boolean):void;
Vungle.vungle.setIncentivizedBackButtonEnabled(backEnabled:Boolean):void;

此类功能仅供向后兼容使用。不建议在新应用程序中使用,或混合在 playAd() 功能调用中。

疑难解答与常见问题

“如何在 Flash Professional CS6 当中把 VungleExample. 用作文档类型?”

  1. 首先创建应用程序,并安装本指南的 1-3 节添加扩展。

  2. 把 VungleExample.以 .fla 格式复制并粘贴到同一文件夹。不要把它的内容复制粘贴到时间线上。会无法运行。

  3. 在第 51 行把应用程序 ID 改为您自己的 Vungle 应用程序 ID。

  4. 在 Flash 属性的“Document Class”(文件类型)属性下,输入“VungleExample”(不要输入引号)并按 OK。

  5. 创建并安装应用程序。

“如何在 Flash Professional CS6 中安装更新版的 AIR SDK(4.0 或更高版本)?”

通过此链接 找到最新版 AIR SDK。若已安装 AIR SDK 4.0 或更高版本,可跳过该步骤。若没有安装,请按以下说明操作:

  1. 解压 AIR 4.0 或最近版本的 SDK 压缩包至您硬盘上的指定位置。

  2. 运行 Flash Professional CS6。

  3. 选择 Help > Manage AIR SDK...(帮助 > 管理 AIR SDK......)

  4. 按加号键(+)并导航至解压 AIR SDK 的位置。

  5. 按 OK

  6. 选择 File > Publish Settings(文件 > 发布设置)

  7. 从“Target”下拉菜单中选择用于 iOS 的最新版 AIR SDK

“如何在 Flash Builder 中安装更新版的 AIR SDK(4.0 或更高版本)?”

通过此链接 找到最新版 AIR SDK。若已安装 AIR SDK 4.0 或更高版本,可跳过该步骤。您也可参阅 Adobe 最新发布的Flash Builder AIR SDK 更新说明

还有其它问题?提交请求

评论