Vungle - Android SDK v. 5 入门指南

目录

要求

  • Android 3.0(Honeycomb - API 版本 11)或更新版本
  • 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,并在所有项目部分添加 Maven URL。

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

为您的应用程序打开app-level build.gradle的文件,并在依赖部分添加编译依赖。

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

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

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

下载 Vungle SDK 并将其添加到您的项目库。

image2.png

打开project-level build.gradle,并更新资源库部分。

allprojects {
    repositories {
        jcenter()
    }
}

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

android{
...
    packagingOptions{
        exclude 'META-INF/rxjava.properties'
    }
...
}

dependencies {
    …
    compile 'com.squareup.retrofit2:converter-gson:2.2.0'
    compile 'com.squareup.retrofit2:adapter-rxjava:2.2.0'
    compile 'com.google.android.gms:play-services-basement:11.4.0'  //use version 11.0.1 and up only
    compile 'com.google.android.gms:play-services-location:11.4.0'  //use version 11.0.1 and up only
    compile files('libs/dagger-2.7.jar')
    compile files('libs/javax.inject-1.jar')
    compile files('libs/eventbus-2.2.1.jar')
    compile files('libs/publisher-sdk-android-5.3.0.jar')
    compile files('libs/rxjava-1.2.0.jar')
    … 
}

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

步骤 2:更新 AndroidManifest.xml

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

<!-- permissions to download and cache video ads for playback --> 
<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" />
<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 回调。

public class FirstActivity extends android.app.Activity {

  // 获取 VunglePub 实例
  final VunglePub vunglePub = VunglePub.getInstance();

  // 设置应用程序后,在 Vungle 仪表板上的应用程序主页上获取应用程序 ID
  
  @Override
  public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);

       // 使用应用程序 id,广告位置参考 id 和初始化回调处理程序来初始化 Publisher SDK
  	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 {

  // 获取 VunglePub 实例
  final VunglePub vunglePub = VunglePub.getInstance();
  final String placementIdForLevel = “your placement reference id”;
final AdConfig globalAdConfig = vunglePub.getGlobalAdConfig(); private void onLevelStart() { vunglePub.loadAd(placementIdForLevel); } private void onLevelComplete() { if (vunglePub.isAdPlayable(placementIdForLevel)) { vunglePub.playAd(placementIdForLevel, globalAdConfig); } } }

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

如要定义用户是否有关闭广告的选项,请使用 Vungle Dashboard 中的强制观看选项。

注:SDK v.5.1. 暂不支持测试模式。

高级设置

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 方法数限制(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 中的 midifyEnabled 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 ; }
-keep class rx.schedulers.ImmediateScheduler { public ; }
-keep class rx.schedulers.TestScheduler { public ; }
-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) {
        // 当用户退出广告,控制转回至您的应用程序时调用
        // 如果 wasSuccessfulView 为 true,表示用户观看了广告,并应获得奖励
        //(如果这是奖励广告)。
        // 如果 wasCallToActionClicked 为 true,表示用户点击了广告中的
        // 行动号召按钮。
      }

    @Override
    public void onAdStart(String placemetReferenceId) {
        // 在播放广告前调用
    }

    @Override
    public void onUnableToPlayAd(String placementReferenceId, String reason) {
        // 在 playAd(placementId, adConfig) 不能播放广告时调用
     }

    @Override
  public void onAdAvailabilityUpdate(String placementReferenceId, boolean isAdAvailable) {
        // 通知所指示的广告位置的广告可用性
  // 可以有重复通知
    }
  };

  @Override
  public void onCreate(Bundle savedInstanceState) {
      ...

      vunglePub.init(this, app_id, placement_id_list, initCallback);
      vunglePub.clearAndSetEventListeners(vungleListener);

  };

 @Override
  public void onDestroy() {
      ...
      vunglePub.clearEventListeners();
      super.onDestroy();

  };
}</>pre

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

public void onSuccess();
public void onFailure(Throwable error);

UI 线程注释

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

配置选项

全局广告配置

调用初始化后,您还必须设置全局 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() {
				// 获得对全局 AdConfig 对象的引用
				final AdConfig globalAdConfig = vunglePub.getGlobalAdConfig();
				// 有关可用选项的完整描述,请参阅‘配置对象’部分。
				globalAdConfig.setSoundEnabled(true);
			}
			@Override
			public void onFailure(Throwable e){

			}
		});
	...
	}
}

单个广告配置

任何时候调用 playAd 时,都必须使用 Adconfig 对象。 但是,通过向 playAd 提供一个新的 AdConfig 对象,您可以选择自定义所播放的每个广告。您在全局广告配置中设置的任何选项将被所提供的选项覆盖。通过以下方法来越过覆盖 AdConfig

public class GameActivity extends android.app.Activity {
  …
private void onLevelComplete() {
      // 创建新的 AdConfig 对象
      final AdConfig overrideConfig = new AdConfig();

      overrideConfig.setSoundEnabled(false);

      // overrideConfig 对象将仅影响此广告播放。
      vunglePub.playAd(yourPlacementId, overrideConfig);
  }
}

AdConfig 对象

覆盖项 AdConfig 有一组可为单个广告播放设置的选项。可用选项如下:

方法

默认

说明

setOrientation

Orientation.matchVideo

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

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

setSoundEnabled

true

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

setBackButtonImmediatelyEnabled

false

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

setImmersiveMode

false

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

setIncentivizedUserId

none

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

setIncentivizedCancelDialogTitle

“关闭视频?”

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

setIncentivizedCancelDialogBodyText

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

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

setIncentivizedCancelDialogCloseButtonText

“关闭视频”

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

setIncentivizedCancelDialogKeepWatchingButtonText

“继续观看”

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

setTransitionAnimationEnabled

false

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

 

还有其它问题?提交请求

评论