Vungle (SDK v.1.0 - v.4.1) - Adobe Air 入门指南

本指南为您展示如何将我们的 Vungle Adobe Air 插件集成到一个基本的示例应用程序。这里引用的源代码可以在我们的公共 GitHub 存储库中获得。

目录

开始之前
1.添加扩展库
2.升级您的应用程序描述符
3.集成 Vungle API
故障排除和常见问题(FAQ)

开始之前

  • Vungle 扩展要求 Adobe AIR SDK 4.0 或更高版本。如需了解关于如何在 Flash Builder 或 Flash Professional 中更新 AIR SDK 的指引,请参阅本指南末尾的“如何更新 AIR SDK?”。

  • 如果您使用的系统是 Android,Vungle AIR 扩展需要开发系统中安装有 JDK 6 或 JDK 7(取决于您正在使用的 Flash 版本)。运行程序需要 Android 3.0(Honeycomb - API 版本 11)或更新版本。

  • 您可以查看ActionScript 3 类文档

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

1.添加扩展库

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

如果面向 Android: 您还需要添加 Google Play Services 库至您的项目。因为许多其他扩展已经含有此库,您可能不需要添加它。如要添加扩展,请重复以下步骤,但使用com.vungle.extensions.android.GooglePlayServices.ane来代替com.vungle.extensions.Vungle.ane

在 Flash Professional CS6 或更高版本中:

  1. 为 Android 或 iOS 项目创建一个新的 AIR。
  2. 选择 文件 > 发布 Settings...
  3. 选择脚本旁边的扳手图标以进入‘ActionScript 设置’。
  4. 库路径选项卡中,点击浏览本地扩展(ANE)文件并选择 com.vungle.extensions.Vungle.ane 文件。点击OK
  5. 选择目标旁边的扳手图标以进入‘ 播放器设置’。
  6. 如果面向 Android:在权限选项卡中,启用‘网络’,‘WRITE_EXTERNAL_STORAGE’,和‘ACCESS_NETWORK_STATE’。
  7. 本应用程序选项选择手动管理权限和清单补充,并点击  OK

在 Flash Builder 4.6 或更高版本中:

  1. 项目属性中,在 Actionscript 构建路径下,选择本地扩展 
  2. 选择添加 ANE... 并前往 com.vungle.extensions.Vungle.ane 文件。
  3. 选择 Actionscript 构建打包 > Google Android
  4. 本地扩展选项卡中,选择扩展旁边的打包选项。
  5. 如果面向 iOS,为 'Apple iOS' 目标重复步骤 3 和 4。

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

为了运行 Vungle,需要为您的应用程序修改应用程序 XML 文件。修改由您的 IDE 创建 XML 文件,变更如下所示(如果您是 Flash Professional 用户,请确保您已遵循以上针对“添加库到 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 扩展。并在此添加其扩展 ID。
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    </extensions>

对于面向 Android 的 AIR 应用程序

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

  • 添加 INTERNETWRITE_EXTERNAL_STORAGE,和 ACCESS_NETWORK_STATE 权限
  • 添加 VideoFullScreenAdActivity 和MraidFullScreenAdActivity 活动定义
  • 添加 google-play-services 版本元数据标签:
<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.VideoFullScreenAdActivity"
     android:configChanges="keyboardHidden|orientation|screenSize"
     android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>
   <activity android:name="com.vungle.publisher.MraidFullScreenAdActivity"
     android:configChanges="keyboardHidden|orientation|screenSize"
     android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"/>
 </application>
</manifest>
]]></manifestAdditions>
</android>

对于面向 iOS 的 AIR 应用程序

如果面向 iOS,当使用 Adobe AIR 21+ 构建时,我们建议通过添加以下内容到应用程序描述符 XML 来禁用应用程序安全传输(ATS):

<iPhone>
    <InfoAdditions>
        <![CDATA[
            <key>NSAppTransportSecurity</key>
            <dict>
                <key>NSAllowsArbitraryLoads</key>
                <true />
            </dict>
        ]]>
    </InfoAdditions>
</iPhone>

请参阅 准备面向 iOS 9 的应用程序 来了解关于应用程序安全传输的更多信息。

3.集成 Vungle API

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

初始化 Vungle 扩展

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

  • 如果使用纯 ActionScript,请在文档类的构造符中进行。
  • 如果使用 Flex,请在主类的 initialize() 事件中调用。
  • 如果在 Flash 中使用时间轴代码,请在 Frame 1 上进行。
  1. 导入 API 类:
    import com.vungle.extensions.*;
    import com.vungle.extensions.events.*;
  2. 通过调用 Vungle.create() 来初始化 API,然后进入一个来自 Vungle Dashboard、含有应用程序 ID 的阵列。如果您从同一个项目同时面向 iOS 和 Android,请添加阵列中的两个 ID,其中 iOS ID 在前,Android ID 在后。

    您应当打包调用 Vungle.create() 到一个 try/catch 程序中,因为 Vungle 可能在创建过程中抛出一个错误(例如,如果在台式机上运行,扩展将抛出一个错误):
    try
    {
     // 使用您的应用程序 id 初始化
     Vungle.create(["your_vungle_id"]);

     // -或者- 为多平台应用程序初始化 ios 和 android 的 id
     // Vungle.create(["your_ios_vungle_id","your_android_vungle_id"]);
    } catch (error:Error) {
     // 无法创建扩展。您在运行 iOS/Android 之外的程序吗?
    }

展示一个插播广告

如要展示一个插播广告,请调用playAd()。您需要先使用 isAdAvailable() 方法检查广告是否可用:

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

展示一个激励广告

如要展示一个激励广告,请调用拥有一个配置对象的 playAd(),并设置奖励选项为 true。您需要先使用 isAdAvailable() 方法检查广告是否可用。

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

如要奖励观看完奖励广告的观众,您将需要执行AD_FINISHED 事件侦听器,如下所述。

添加事件侦听器

Vungle Extension 发送四个事件:VungleEvent.AD_PLAYABLE, VungleEvent.AD_STARTED, VungleEvent.AD_FINISHED, 和 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, CTA = " + e.wasCallToActionClicked);
     if (e.wasSuccessfulView)
     {
       trace("counts a completed view - present reward.");
     }
    }
  3. 当 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);
    }

更多选项

如您之前所见,调用 playAd() 方法时,您可以传递一个拥有配置选项的对象。这些是 VungleAdConfig 中的可用属性:

方向

通过此属性,您可以规定广告的方向。Android 和 iOS 拥有不同的标记,请参阅 VungleOrientation 类以了解详细信息。标记可以结合一个按位 OR 运算符:

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

soundEnabled

您可以使用此属性来控制广告是否播放声音或静音。

backButtonImmediatelyEnabled

此选项只面向 Android。如果为 true,用户可以立即使用返回按钮退出广告。如果为 false,在屏幕上的关闭按钮显示之前用户不可以使用返回按钮退出广告。

immersiveMode

此选项只面向 Android。它在 KitKat+ 设备上启用或禁用沉浸模式

奖励

设置奖励模式。如果为 true,用户在试图跳过广告时将会看到一个确认对话窗口。

incentivizedUserId

将被传递至您的应用程序的唯一用户 ID,用以验证该用户是否应当因为观看了奖励广告而获得奖励。

incentivizedCancelDialogTitle, incentivizedCancelDialogBodyText, incentivizedCancelDialogCloseButtonText, incentivizedCancelDialogKeepWatchingButtonText

这些选项让您自定义跳过奖励广告时出现的确认对话窗口。

extra1 … extra8

即将到来——您可以用这个来跟踪指标,例如年龄组、性别等。

广告位置

即将来临——一项可选的广告位置名称,当通过 Vungle Reporting API 请求数据时,用于加强的数据分类。

largeButtons

此选项只面向 iOS。如果设为 true, 显示在视频上的屏幕按钮将会更大。

全局默认值

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


// 设置任何您喜欢的配置选项
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() 方法调用混合。

注意: 当您的应用程序处于测试模式时,您将无法下载任何通告的应用程序。此外,Dashboard 不会报告展示次数。这是因为测试广告仅用于验证您是否已正确集成 SDK。一旦您的应用程序在活动模式下可用,即可使用此功能。

故障排除和常见问题

“我如何在 Flash Professional CS6 中使用 VungleExample.as 文档类?”

  1. 首先,根据本指南第 1-3 节的指引创建应用程序和添加扩展。
  2. 复制和粘贴 VungleExample.as 到同一个文件夹以作为您的 .fla 文件。请不要复制和粘贴其内容到时间轴上。那将无法运行。
  3. 将第 51 行中的应用程序 id 修改为您自己的 Vungle 应用程序 id。
  4. 在 Flash 属性中,在‘文档类’下,输入 'VungleExample'(无引号)并按下 OK。
  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. 按下 OK
  6. 选择文件 > 发布设置
  7. 从‘目标’下拉菜单中选择面向 iOS 的最新 AIR SDK

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

请沿此链接去寻找最新版本的 AIR SDK。如果您已经安装了 AIR 4.0 或更高版本,您可以跳过此步骤。您还可以使用 Adobe 的最新指引来更新 Flash Builder AIR SDK

“我遇到一个‘Adobe Animate 无效输入’的错误。我该怎么办?”

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

还有其它问题?提交请求

评论