Vungle - Android 或 Amazon SDK v. 5 入门指南

本文介绍如何集成 Vungle 的 Android SDK 或 Amazon SDK。从 Android SDK v.5.3.2 开始,Vungle 支持 Amazon OS 5.4 及更高版本。Amazon SDK 的集成步骤与 Android 相同。

目录

要求

  • Android 4.0(Ice Cream Sandwich - API 版本 14)或更高版本
  • Java 1.7 - 出于兼容 Android 5.+ 的目的,需要安装 JDK 7
  • Java 1.8 - 出于兼容 Android 7.+ 的目的,需要安装 JDK 8

步骤 1:将 VungleSDK 添加到您的项目中

Vungle SDK 可通过两种方式获取:AAR(通过 Maven)文件,或手动下载。

选项 1:将 Vungle SDK 添加为 AAR(通过 Maven)

打开项目级别的 build.gradle,并在“all projects”部分添加 Maven URL。

allprojects { repositories { maven { url 'https://jitpack.io' } } }

打开 app-level build.gradle 文件,并在“dependencies”部分添加编译依赖项。

dependencies { … compile 'com.github.vungle:vungle-android-sdk:5.3.2'
compile 'com.google.android.gms:play-services-basement:11.0.4' //This library is optional, but if used, use version 11.0.1 and up only compile 'com.google.android.gms:play-services-location:11.0.4' //This library is optional, but if used, use version 11.0.1 and up only
… }

如果已添加 Vungle SDK(通过 Maven),则可跳过“步骤 2:更新 AndroidManifest.xml”。

选项 2:下载 Vungle SDK 并将其添加到您的应用程序中

下载 Vungle SDK 并解压,然后前往 libs 文件夹,复制所有的 jar 文件并将其添加到您的项目库。

Screen_Shot_2017-10-05_at_2.51.15_PM.png

打开 project-level build.gradle,然后更新“repositories”部分。

allprojects { repositories { jcenter() } }

打开应用程序级别的 build.gradle 文件,并在“dependencies”部分添加其他依赖项。

android{ ... packagingOptions{ exclude 'META-INF/rxjava.properties' } ... } dependencies { … compile files('libs/adapter-rxjava-2.2.0.jar') compile files('libs/converter-gson-2.2.0.jar') compile files('libs/dagger-2.7.jar') compile files('libs/eventbus-2.2.1.jar') compile files('libs/gson-2.7.jar') compile files('libs/javax.inject-1.jar') compile files('libs/okhttp-3.6.0.jar') compile files('libs/okio-1.11.0.jar') compile files('libs/publisher-sdk-android-5.3.2.jar') compile files('libs/retrofit-2.2.0.jar') compile files('libs/rxjava-1.2.0.jar') compile 'com.google.android.gms:play-services-basement:11.0.4' //use version 11.0.1 and up only compile 'com.google.android.gms:play-services-location:11.0.4' //use version 11.0.1 and up only … } 

如果手动添加 Vungle SDK,请继续执行“步骤 2:更新 AndroidManifest.xml”。

步骤 2:更新 AndroidManifest.xml

将以下几行添加到您的 AndroidManifest.xml,然后将应用程序项目名称分配给应用程序类名称以用于分包:

<!-- Required permissions for caching and ad operations to work -->
<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 to enable better geo-targeting of ads (recommended) -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<application
android:name=".(YourApplicationName)"
...
<activity android:name="com.vungle.publisher.VideoFullScreenAdActivity"
android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>

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

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

步骤 3:初始化 Vungle SDK

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

应用程序启动

使用您想在应用程序里面使用的有效广告位置参考 ID 在应用程序的首个 Activity 中初始化 Vungle Publisher SDK。SDK 将被异步初始化,并对初始化过程中提供的 VungleInitListener 返回一个回调。

注:如果在调用 init 方法时使用的 App ID 不正确,则 Vungle SDK 将不会初始化,也不会触发 onFailure 回调。如果在调用 init 方法时使用的广告位置 ID 不正确,则 Vungle SDK 初始化,但该广告位置将无法加载广告,且始终对 isAdPlayable 返回 false。同样,系统不会对不正确的广告位置 ID 触发 onFailure 回调。

public class FirstActivity extends android.app.Activity { // get the VunglePub instance final VunglePub vunglePub = VunglePub.getInstance(); // get your App ID from the app's main page on the Vungle Dashboard after setting up your app @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // initialize Publisher SDK with app id, placement reference id list and init callback handler vunglePub.init(this, app_id, new String[] { placementID1, placementID2, placementID3 }, new VungleInitListener() { @Override public void onSuccess() { } @Override public void onFailure(Throwable e){ } }); } }

每个 Activity

此外,重写每个 Activity(包括首个 Activity)中的 onPauseonResume 方法,以确保 Vungle Android SDK 在应用程序获得或失去焦点时进行正确更新。

public class EachActivity extends android.app.Activity { // get the VunglePub instance final VunglePub vunglePub = VunglePub.getInstance(); ... @Override protected void onPause() { super.onPause(); vunglePub.onPause(); } @Override protected void onResume() { super.onResume(); vunglePub.onResume(); } }

步骤 4:设置侦听器

Vungle SDK 会发起多个您可以编程方式对其处理的事件,执行 VungleAdEventListener 类并使用 clearAndSetEventListeners 来注册这些类。牢记在不需要使用事件侦听器时将其删除以防止内存泄露。

vunglePub.clearAndSetEventListeners(vungleDefaultListener, vungleSecondListener);

步骤 5:加载和播放广告

当 Vungle SDK 成功初始化后,您可以加载广告位置并在广告就绪时播放该广告。如果设置了 VungleAdEventListener,则在有可播放的广告时,它会通过 onAdAvailabilityUpdate(String placementReferenceId, boolean isAdAvailable) 回调发出通知。

public class GameActivity extends android.app.Activity { // get the VunglePub instance final VunglePub vunglePub = VunglePub.getInstance(); final String placementIdForLevel = "your placement reference id"; private void onLevelStart() {() { vunglePub.loadAd(placementIdForLevel); } private void onLevelComplete() { if (vunglePub.isAdPlayable(placementIdForLevel)) { vunglePub.playAd(placementIdForLevel, globalAdConfig); } } }

注意,无需对自动缓存的广告位置调用 loadAd,因为 SDK 会在初始化后自动加载广告。我们建议选择观看次数最多的广告位置用于自动缓存。

若要定义用户是否有权关闭广告,请在 Vungle 管理面板上使用强制观看选项。

高级设置

Google Play Services(可选)

在项目中添加 Google Play Services 之后,Vungle 即可为终端用户提供更加个性化的广告体验,但这并非必需要求。我们建议使用 8.4.0 或更高版本。

如要添加 Google Play Services,我们建议您查阅 Google 设置指南。在您的应用程序中,请确保设备已安装版本足够新的 Google Play Services。Vungle SDK 随意使用来自 Google Play Services 的广告位置和广告 API。

  • google.android.gms:play-services-location:11.0.1
  • google.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。

65K Dalvik 方法数限制

将 Vungle Android SDK 5.1.0 添加到项目中时,会增加 6,557 个方法,且不包括任何其他所需的依赖项。我们确有计划要减少项目中的方法数,这是当前的限制情况。请考虑以下建议来减少添加到项目中的方法总数。

  • 选择性 Gradle 编译: Google Play Services (GPS) SDK 拥有约 20K 方法数。如果您的项目使用了 GPS,系统则提供一个选项,您可根据项目需要选择性编译 GPS SDK
    • com.google.android.gms:play-services-location:11.0.1
    • com.google.android.gms:play-services-ads:11.0.1

  • ProGuard:您可以启用 ProGuard 缩减项目代码数量。它在编译时会丢弃所有未使用的类,尽量减少方法总数。ProGuard 的启用方法:在 build.gradle 中对相应的 build 类型指定 minifyEnabled true,并提供相关规则,只保留项目必需的类。

  • Multidex:如果方法总数仍然高于 65K,启用 multiDex 可能是 Google 提供的唯一方法。您需要配置您的项目以便只启动一次 multiDex,但这会影响 build 和应用程序启动时间。

Proguard

如果正在使用 Proguard,请在 ProGuard 配置文件中添加以下规则:

# Vungle -dontwarn com.vungle.** -dontnote com.vungle.** -keep class com.vungle.** { *; } -keep class javax.inject.* # GreenRobot -dontwarn de.greenrobot.event.util.** # RxJava -dontwarn rx.internal.util.unsafe.** -keepclassmembers class rx.internal.util.unsafe.*ArrayQueue*Field* { long producerIndex; long consumerIndex; } -keepclassmembers class rx.internal.util.unsafe.BaseLinkedQueueProducerNodeRef { rx.internal.util.atomic.LinkedQueueNode producerNode; } -keepclassmembers class rx.internal.util.unsafe.BaseLinkedQueueConsumerNodeRef { rx.internal.util.atomic.LinkedQueueNode consumerNode; } -keep class rx.schedulers.Schedulers { public static <methods>; } -keep class rx.schedulers.ImmediateScheduler { public <methods>; } -keep class rx.schedulers.TestScheduler { public <methods>; } -keep class rx.schedulers.Schedulers { public static ** test(); }
# MOAT -dontwarn com.moat.** -keep class com.moat.** { public protected private *; }
# Retrofit -dontwarn okio.** -dontwarn retrofit2.Platform$Java8

事件侦听器界面

可用于处理 VungleAdEventListener 的方法如下:

方法

说明

clearAndSetEventListeners(VungleEventListener..)

清除已注册的事件侦听器,然后添加输入事件侦听器。

clearEventListeners( )

清除所有事件侦听器

removeEventListeners(VungleEventListener..)

删除输入事件侦听器。

addEventListeners(VungleEventListener..)

添加输入事件侦听器

VungleAdEventListener 委派调用 API:

public class FirstActivity extends android.app.Activity { private final VungleAdEventListener vungleListener = new VungleAdEventListener(){ @Override public void onAdEnd(String placementReferenceId, boolean wasSuccessfulView, boolean wasCallToActionClicked) { // Called when user exits the ad and control is returned to your application // if wasSuccessfulView is true, the user watched the ad and should be rewarded // (if this was a rewarded ad). // if wasCallToActionClicked is true, the user clicked the call to action // button in the ad. } @Override public void onAdStart(String placementReferenceId) { // Called before playing an ad } @Override public void onUnableToPlayAd(String placementReferenceId, String reason) { // Called after playAd(placementId, adConfig) is unable to play the ad } @Override public void onAdAvailabilityUpdate(String placementReferenceId, boolean isAdAvailable) { // Notifies ad availability for the indicated placement // There can be duplicate notifications } }; @Override public void onDestroy() { vunglePub.clearEventListeners(); super.onDestroy(); }; }

UI 线程注释

回调在后台线程中执行,因此任何由事件回调导致的 UI 交互或更新在执行之前都必须传递到主 UI 线程。在 UI 线程中运行代码的两个常见方法:

配置选项

全局广告配置

调用 init 后,您还必须设置全局 AdConfig 对象。默认情况下,您可以在每个 playAd 调用中使用此 AdConfig 对象。通过此对象还可以设置会在每个所播放广告中自动应用的选项。

public class FirstActivity extends android.app.Activity { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); vunglePub.init(this, app_id, placement_list, new VungleInitListener() { @Override public void onSuccess() { // get a reference to the global AdConfig object final AdConfig globalAdConfig = vunglePub.getGlobalAdConfig(); // For a full description of available options, see the 'Config Object'section. globalAdConfig.setSoundEnabled(true); } @Override public void onFailure(Throwable e) { } }); } } 

单个广告配置

任何时候调用 playAd 时,都必须使用 AdConfig 对象。但您可以选择通过向 playAd 提供新的 AdConfig 对象来定制每个要播放的广告。如果已在全局广告配置中设置了任何选项,这些全局选项将被 AdConfig 中的选项覆盖。覆盖项 AdConfig 可通过以下方法传递:

public class GameActivity extends android.app.Activity { … private void onLevelComplete() { // create a new AdConfig object final AdConfig overrideConfig = new AdConfig(); overrideConfig.setSoundEnabled(false); // the overrideConfig object will only affect this ad play. vunglePub.playAd(yourPlacementId, overrideConfig); } }

AdConfig 对象

覆盖项 AdConfig 有一组可对单个广告播放进行设置的选项。

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

可用选项如下:

方法

默认

说明

setOrientation

Orientation.matchVideo

Orientation.autoRotate 表示广告将随设备方向自动旋转。

Orientation.matchVideo 表示广告将采用最适合视频的朝向播放(通常是横向)。

setSoundEnabled

true

设置广告的开始声音状态。如果为“true”,音频遵循设备的音量和声音设定。如果为“false”,视频开始时为静音,但用户可自行调节。

setBackButtonImmediatelyEnabled

false

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

setImmersiveMode

false

在 KitKat+ 设备上启用或禁用沉浸模式

setIncentivizedUserId

设置一个可传递至应用程序的唯一用户 ID,用于验证该用户因观看激励式广告所应获得的奖励。如果为非激励式广告,则为 N/A。

 

setIncentivizedCancelDialogTitle

“关闭视频?”

设置跳过激励式广告时的确认对话窗口标题。如果为非激励式广告,则为 N/A。

setIncentivizedCancelDialogBodyText

“提前关闭此视频将无法获得奖励。是否确定继续?”

设置跳过激励式广告时的确认对话窗口正文。如果为非激励式广告,则为 N/A。

setIncentivizedCancelDialogCloseButtonText

“关闭视频”

设置跳过激励式广告时确认对话窗口中的“取消”按钮文字。如果为非激励式广告,则为 N/A。

setIncentivizedCancelDialogKeepWatchingButtonText

“继续观看”

设置跳过激励式广告时确认对话窗口中的“继续观看”按钮文字。如果为非激励式广告,则为 N/A。

setTransitionAnimationEnabled

false

启用或禁用标准片段过渡动画

setOrdinalViewCount(int)

null

如果收到来自 Vungle 的有序数据报告,则使用此字段来传递调解序数。这是一个整数,表示此广告在游戏会话中的显示顺序(例如,如果此会话中已显示了两个广告,且 Vungle 的这个广告会在第三个显示,则传递“3”)。单击此处详细了解有序数据。

getOrdinalViewCount

使用此代码获取之前通过 setOrdinalViewCount 传递的值。

setFlexViewCloseTimeInSec

这是 Flex View 视频在自动关闭之前播放的秒数。

Flex View 广告

要通过编程方式关闭 Flex View 广告,请使用 vunglePub 函数:

vunglePub.closeFlexViewAd(placementID2);

补充说明

Android Studio 中有一个可能造成系统崩溃的已知问题(如下所示)。如果拥有最新的 Android Studio Instant Run,请禁用 Android Studio Instant Run 以避免发生崩溃。

1-20 13:53:03.649 27642-27828/com.publisher.sample W/GooglePlayServicesUtil: Google Play services out of date. Requires 10240000 but found 9879438 
11-20 13:53:03.659 27642-27828/com.publisher.sample W/VungleDevice: Google Play Services not available: SERVICE_VERSION_UPDATE_REQUIRED
11-20 13:53:05.679 27642-27642/com.publisher.sample D/Event: No subscribers registered for event class com.vungle.publisher.lu
11-20 13:53:05.679 27642-27642/com.publisher.sample D/Event: No subscribers registered for event class de.greenrobot.event.NoSubscriberEvent
还有其它问题?提交请求

评论