Vungle - Android SDK v. 5 入门

请使用本文来为 Android 或 Amazon 集成 Vungle 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:添加 Vungle SDK 到您的项目

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

选项 1:以通过 Maven 上的 AAR 文件形式添加 Vungle SDK

打开项目级别的 build.gradle,并在allprojects部分添加 Maven 地址。

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

打开应用级别的build.gradle,并在dependencies部分添加编译依赖。

dependencies {
    …
    compile 'com.github.vungle:vungle-android-sdk:5.3.2'
… }

如果您利用 Maven 添加 Vungle SDK,您可以跳过步骤 2. 更新 AndroidManifest.xml”。

选项 2:下载 Vungle SDK 并将其添加到您的工程

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

Screen_Shot_2017-10-05_at_2.51.15_PM.png

打开项目级别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'  //可选,但是如果使用,请使用version 11.0.1 或以上
    compile 'com.google.android.gms:play-services-location:11.0.4'  //可选,但是如果使用,请使用version 11.0.1 或以上
    … 
}

如果您手动添加 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

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

应用程序启动

请在首个 Activity 中初始化 Vungle Publisher SDK。SDK 将被异步初始化,并返回 VungleInitListener 回调。

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

此外,需要在调用Vungle SDK的每个 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 Dashboard 上勾选强制观看选项。

高级设置

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 及以下版本:请保留support library
  • 对于 Google Play Services 8.4.0 及以上版本:不需要support library

我们已经成功编译了独立的 SDK 以便与以下版本的 Google Play Services 进行编译:7.8.0, 8.4.0, 9.8.0, 10.2.4, 11.0.1.

65K 方法数限制(65K Dalvik Method Limit)

添加 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 来缩小您的项目代码。它会在编译时抛弃任何未使用的类以使总方法数尽可能地小。启用方法是指定 build.gradle 中的 minifyEnabled true 以得到恰当的构建类型并提供规则来保留您项目所需的类。

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

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

EventListener 接口

VungleAdEventListener 回调如下:

方法

说明

clearAndSetEventListeners(VungleEventListener..)

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

clearEventListeners( )

清除所有 EventListeners

removeEventListeners(VungleEventListener..)

删除事件侦听器。

addEventListeners(VungleEventListener..)

添加 eventListeners

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();
  };
}

Vungle 还为 SDK 初始化事件更新提供 VunlgeInitListner

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 对象对单个广告进行配置。全局广告配置中的设置,将会被在 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 中,我们使用术语“激励”。

奖励广告与插屏广告类型在Vungle Dashboard创建时进行选择,无需在代码中设置。

可用选项如下:

方法

默认

说明

setOrientation

Orientation.matchVideo

Orientation.autoRotate 指示广告将根据设备的方向自动旋转。

Orientation.matchVideo 指示视频广告将以最佳方向播放(通常是横向)。

setSoundEnabled

true

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

setBackButtonImmediatelyEnabled

false

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

setImmersiveMode

false

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

setIncentivizedUserId

none

将您的唯一用户 ID 设置为传递至您的应用程序中,以验证该用户观看了奖励广告应获得奖励。如果广告没有奖励,则为 N/A。只在S2S回调中使用。

 

setIncentivizedCancelDialogTitle

“关闭视频?”

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

setIncentivizedCancelDialogBodyText

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

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

setIncentivizedCancelDialogCloseButtonText

“关闭视频”

设置跳过奖励广告时确认对话窗口的“取消按钮”。如果广告没有奖励,则为 N/A。

setIncentivizedCancelDialogKeepWatchingButtonText

“继续观看”

设置跳过奖励广告时确认对话窗口的“继续观看按钮”。如果广告没有奖励,则为 N/A。

setTransitionAnimationEnabled

false

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

setOrdinalViewCount(int)

null 

If you receive ordinal data reports from Vungle, use this field to pass the mediation ordinal. This is an integer indicating the order in which this ad was shown in the game session (for example, if two ads were already shown in this session, and this ad from Vungle was then shown third, pass in '3'). Read more about ordinal data here

getOrdinalViewCount

none 

Use this to get the value you passed in through setOrdinalViewCount.

setFlexViewCloseTimeInSec

none

This the the amount of seconds the flex view videos will play before they automatically close. 

Flex View Ads

为了主动关闭Flex View广告,可以使用vunglePub 类:

vunglePub.closeFlexViewAd(placementID2);

备注

Android Studios 有一个已知的问题。可能会导致崩溃。如果正在使用最新的Instant Run,请关闭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
还有其它问题?提交请求

评论