将 Vungle Android SDK 从 v. 5 版本迁移到 v. 6 版本

欢迎使用 Vungle Android SDK v6 迁移指南!新版 SDK 已全部重新编写,兼具了鲁棒性与轻量化。本文档可以指导您完成 SDK 升级,因为 API 和集成方面的详细信息都有了重大变化。如果您要全新集成,而非从 v5 SDK 迁移,请使用集成 Vungle Android SDK v6 指南,而不是本文档。

本文内容:

GDPR:推荐实施方法

《通用数据保护条例》(GDPR) 将于 5 月 25 日在欧盟生效。为了遵守 GDPR,开发者有以下两种选择。

  • 选项 1(推荐):发布商从用户级别控制 GDPR 的同意流程,然后将用户的选择传达给 Vungle。为此,开发人员可以使用自己的机制来收集用户的同意信息,然后使用 Vungle API 更新或查询用户的同意状态。若需了解详细信息,请参阅“GDPR 推荐实施方法说明”部分。

  • 选项 2:允许 Vungle 处理相关需求。Vungle 在向欧洲用户播放广告之前会显示征求同意的对话框,并记住用户的同意或拒绝选择,以用于后续的广告。

开始之前

版本特点

  • 快速:初始化和广告缓存速度比 v5 快五倍
  • 轻量:减少了方法数量
    • 核心 SDK:750 个方法
    • 全面集成(含第三方库):~4000 个方法
  • GDPR 合规性:Vungle 提供了两种为获得用户同意的选项:由 Vungle 或由发布商控制此流程。并增加了新的 API 调用。

要求

  • Android 4.0(Ice Cream Sandwich - API 版本 14)或更高版本

示例应用程序

步骤 1:在项目中更改 Vungle SDK

根据项目设置情况,使用 AAR 集成(通过 Maven),或使用 JAR 进行手动集成。

选项 1:Gradle 集成

dependencies {
compile 'com.github.vungle:vungle-android-sdk:6.2.3'
compile 'com.google.android.gms:play-services-basement:11.0.1' // Required
compile 'com.google.android.gms:play-services-location:11.0.1' // Recommended
}

跳到“步骤 2:导入 Vungle SDK”。

选项 2:JAR 集成

下载 Vungle SDK v6,并将旧版 Vungle SDK 和第三方依赖项 JAR 文件替换为新的 SDK 和库。请注意所需库的增加和减少以及相关版本更新。

v5 库 v6 库
image3.png image2.png

编译 SDK 下载包中的所有 JAR 文件。

dependencies { // Vungle SDK compile files('libs/vungle-android-sdk-6.2.5.jar') // Required Third-party Dependencies compile files('libs/android-job-1.2.0.jar') compile files('libs/cat-1.0.5.jar') compile files('libs/converter-gson-2.2.0.jar') compile files('libs/fetch-1.1.5.jar') compile files('libs/gson-2.7.jar') compile files('libs/logging-interceptor-3.7.0.jar') compile files('libs/okhttp-3.7.0.jar') compile files('libs/okio-1.12.0.jar') compile files('libs/retrofit-2.2.0.jar') compile files('libs/VNG-moat-mobile-app-kit-2.2.0.jar') // Google Play Services compile 'com.google.android.gms:play-services-gcm:11.0.4' // Required compile 'com.google.android.gms:play-services-basement:11.0.4' // Optional compile 'com.google.android.gms:play-services-location:11.0.4' // Optional }

修改 AndroidManifest.xml.

<!--Required Permissions-->
<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.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WAKE_LOCK" /> <!--Optional Permissions-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/AppTheme"
android:networkSecurityConfig="@xml/network_security_config" > <activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity> <!-- Google Play Services -->
<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" /> <!-- Vungle -->
<activity
android:name="com.vungle.warren.ui.VungleActivity"
android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
android:launchMode="singleTop"
android:theme="@android:style/Theme.Translucent.NoTitleBar" /> <!-- android-job -->
<service
android:name="com.evernote.android.job.v21.PlatformJobService"
android:exported="false"
android:permission="android.permission.BIND_JOB_SERVICE" />
<service
android:name="com.evernote.android.job.v14.PlatformAlarmService"
android:exported="false"
android:permission="android.permission.BIND_JOB_SERVICE" />
<service
android:name="com.evernote.android.job.v14.PlatformAlarmServiceExact"
android:exported="false" />
<receiver
android:name="com.evernote.android.job.v14.PlatformAlarmReceiver"
android:exported="false" >
<intent-filter>
<!-- Keep the filter for legacy intents -->
<action android:name="com.evernote.android.job.v14.RUN_JOB" />
<action android:name="net.vrallev.android.job.v14.RUN_JOB" />
</intent-filter>
</receiver>
<receiver
android:name="com.evernote.android.job.JobBootReceiver"
android:exported="false" >
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
<action android:name="android.intent.action.QUICKBOOT_POWERON" />
<action android:name="com.htc.intent.action.QUICKBOOT_POWERON" />
<action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
</intent-filter>
</receiver>
<service
android:name="com.evernote.android.job.gcm.PlatformGcmService"
android:enabled="false"
android:exported="true"
android:permission="com.google.android.gms.permission.BIND_NETWORK_TASK_SERVICE" >
<intent-filter>
<action android:name="com.google.android.gms.gcm.ACTION_TASK_READY" />
</intent-filter>
</service>
<service
android:name="com.evernote.android.job.JobRescheduleService"
android:exported="false"
android:permission="android.permission.BIND_JOB_SERVICE" /> </application>

步骤 2:导入 Vungle SDK

// v5 Import SDK
import com.vungle.publisher.*;

// v6 Import SDK
import com.vungle.warren.*;

步骤 3:初始化 Vungle SDK

以前在进行初始化时,您必须先抓取 Vungle SDK 实例并发布 init()。此方法会调用 Vungle 应用程序 ID 以及一个包含广告位置参考 ID 和 VungleInitListener 的字符串数组,如下所示:

// v5 Initialization
private final VunglePub vunglePub = VunglePub.getInstance();
private final String[] placement_array = {"PLACEMENT_1", "PLACEMENT_2", "PLACEMENT_3"};
...
vunglePub.init(this, app_id, placement_array, new VungleInitListener() {
@Override
public void onSuccess() { }

@Override
public void onFailure(Throwable e) { }
});
}

新的初始化方法则调用不同的参数,顺序也不相同:

  • 使用的广告位置参考 ID 的字符串列表
  • Vungle 应用程序 ID
  • 应用程序上下文
  • InitCallback
    • onSuccess在 SDK 成功完成初始化时发出通知
    • onError在初始化失败时发出通知
      • InitCallback 为空时抛出 IllegalArgumentException
      • 在所需参数丢失或无效时抛出 VungleException
    • onAutoCacheAdAvailable在自动缓存位置上有可播放的广告时发出通知

onAutoCacheAdAvailablecallback 可作为初始化回调的一部分,因为只要广告没有预缓存,SDK 就会不断尝试缓存用于自动缓存广告位置的广告。这包括 SDK 初次启动时或者该位置的预缓存广告已播放时。这将保持为 true,直到进程结束或 Vungle 实例被垃圾收集回收。对于所有其他非自动缓存的广告位置,必须按照“步骤 5:加载广告”中的说明明示发布 loadAd

// v6 Initialization
private final List<String> placement_collection = Arrays.asList("PLACEMENT_1", "PLACEMENT_2", "PLACEMENT_3");

Vungle.init(placement_collection, app_id, this.getApplicationContext(), new InitCallback() {
@Override
public void onSuccess() {
// Initialization has succeeded and SDK is ready to load an ad or play one if there
// is one pre-cached already
}

@Override
public void onError(Throwable throwable) {
// Initialization error occurred - throwable.getMessage() contains error message
}

@Override
public void onAutoCacheAdAvailable(String placementId) {
// Callback to notify when an ad becomes available for the auto-cached placement
//
// NOTE: This callback works only for the auto-cached placement. Please use
// LoadAdCallback interface for other placements
}
};

您可以随时通过调用 isInitialized 方法来检查 Vungle SDK 是否已初始化:

public static boolean isInitialized() 

步骤 4:事件侦听器

SDK v5 中的全局 VungleAdEventListener 在 SDK v6 已被替换为两个独立的回调(加载和播放事件)。请从项目中移除 SDK v5 的 VungleAdEventListener 实施方法:

// Remove v5 Event Listener
public class FirstActivity extends android.app.Activity {

private final VungleAdEventListener vungleListener = new VungleAdEventListener(){

@Override
public void onAdEnd(String placementReferenceId, boolean wasSuccessfulView, boolean wasCallToActionClicked) { }

@Override
public void onAdStart(String placementReferenceId) { }

@Override
public void onUnableToPlayAd(String placementReferenceId, String reason) { }

@Override
public void onAdAvailabilityUpdate(String placementReferenceId, boolean isAdAvailable) { }
};

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

如果要对所有事件使用通用回调,现在您可对广告加载事件执行 LoadAdCallback,对广告播放事件执行 PlayAdCallback。否则,则跳到“步骤 5:加载广告”执行内联回调。

// Implement v6 LoadAdCallback
private final LoadAdCallback vungleLoadAdCallback = new LoadAdCallback() {
@Override
public void onAdLoad(String placementReferenceId) {
// Placement reference ID for the placement to load ad assets
}

@Override
public void onError(String placementReferenceId, Throwable throwable) {
// Placement reference ID for the placement that failed to download ad assets
// Throwable contains error message
}
};

 

// Implement v6 PlayAdCallback
private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() {
@Override
public void onAdStart(String placementReferenceId) {
// Placement reference ID for the placement to be played
}

@Override
public void onAdEnd (String placementReferenceId, boolean completed, boolean isCTAClicked) {
// Placement reference ID for the placement that has completed ad experience
// completed has value of true or false to notify whether video was
// watched for 80% or more
// isCTAClkcked has value of true or false to indicate whether download button
// of an ad has been clicked by the user
}

@Override
public void onError(String placementReferenceId, Throwable throwable) {
// Placement reference ID for the placement that failed to play an ad
// Throwable contains error message
}
};

步骤 5:加载广告

两个版本的加载广告方式大致相同,主要区别是在 v6 中,允许按负载回调,而不是像 v5 那样依靠全局 VungleAdEventListenerLoadAdCallback 会获得有关所分配调用的负载状态的通知。v6 SDK 仅引用此回调且不会将其存储在任何地方;调用方应确保对回调的妥善管理。

// v5 loadAd
public void loadAd(@NonNull String placementReferenceId)

// v6 loadAd
public static void loadAd(@NonNull final String id, @Nullable LoadAdCallback callback)

SDK 会管理自动缓存广告位置的广告资产下载,因此无需为自动缓存广告位置调用此方法。对于所有其他广告位置,必须调用并成功完成 loadAd 方法,然后 SDK 才能播放该位置的广告。发生上述情况时会触发 onAdLoad 回调。

// v6 Load Ad Implementation
if (Vungle.isInitialized()) {
Vungle.loadAd("PLACEMENT_ID", new LoadAdCallback() {
@Override
public void onAdLoad(String placementReferenceId) { }

@Override
public void onError(String placementReferenceId, Throwable throwable) { }
};
}

步骤 6:检查广告可用性

“检查可用性”的方法与 v5 基本相同,唯一的区别是现在采用了静态方法,而不是实例方法。

 // v5 isAdPlayable
public boolean isAdPlayable(@NonNull final String placementReferenceId)

// v6 canPlayAd
public static boolean canPlayAd(@NonNull String id)

步骤 7:播放广告

与广告加载方式的变化类似,播放广告所需的信息与 v5 中相同,可选择将 PlayAdCallback 传递给方法,这样即可在广告播放过程中收到成功或失败的通知。

// v5 playAd
public void playAd(@NonNull String placementReferenceId, @Nullable AdConfig adConfig)

// v6 playAd
public static void playAd(@NonNull final String id, final AdConfig settings, @Nullable final PlayAdCallback listener)

在调用 playAd 方法之前,应始终通过调用 canPlayAd 方法来检查广告的可用性。在从初始 playAd 调用收到 onAdEndonError 回调之前,必须确保不发布其他 playAd,因为如果快速反复调用 playAd,广告将无法正确呈现。

// v6 Play Ad Implementation
if (Vungle.canPlayAd("PLACEMENT_ID")) {
Vungle.playAd("PLACEMENT_ID", new AdConfig, new PlayAdCallback() {
@Override
public void onAdStart(String placementReferenceId) { }

@Override
public void onAdEnd(String placementReferenceId, boolean completed, boolean isCTAClicked) { }

@Override
public void onError(String placementReferenceId, Throwable throwable) { }
});
}

步骤 8:配置选项

广告播放选项

下表列出了所有可用的 AdConfig 选项。

选项

说明

setBackButtonImmediatelyEnabled

如果想要在广告关闭按钮出现之前启用后退按钮,则为 true;否则为 false

setFlexViewCloseTime

应为大于或等于 0 的整数值,用于指定 Flex-View 广告自动关闭的时间(以秒为单位)

setImmersiveMode

如果要为 KitKat+ 设备启用沉浸模式,则为 true,否则为 false

setAutoRotate

如果视频广告需要自动旋转,则为 true;否则为 false,即按照视频广告的方向

setMuted

如果视频开始时的音频设置应与封闭应用程序的音频设置匹配,则为 true;如果视频一开始就应该是静音,则为 false

setOrdinal

应为序数整数值,用于跟踪同一会话中播放的广告数

setTransitionAnimationEnabled

如果启用视频过渡动画,则设为 true;禁用则设为 false

定制奖励式广告

在 v5 中,奖励式广告的弹出消息对话框可通过 AdConfig 对象进行配置,但现在 v6 中提供了一种新方法,即 setIncentivizedFields

public static void setIncentivizedFields(@Nullable String userID, @Nullable String title, @Nullable String body, @Nullable String keepWatching, @Nullable String close) 

关闭 Flex-View 广告

Flex-View 可以通过编程方式关闭,即使用当前正在播放 Flex-View 广告的广告位置参考 ID 发布 closeFlexViewAd 方法即可。

public static boolean closeFlexViewAd(@NonNull final String placementReferenceId) 

有效广告位置列表

一种帮助程序方法,可返回其中含有当前会话中所有有效广告位置参考 ID 的一系列字符串。

public static Collection<String> getValidPlacements() 

ProGuard 规则

# Vungle -keep class com.vungle.warren.** { *; } # Evernote -dontwarn com.evernote.android.job.gcm.** -dontwarn com.evernote.android.job.GcmAvailableHelper -dontwarn com.google.android.gms.ads.identifier.** -keep public class com.evernote.android.job.v21.PlatformJobService -keep public class com.evernote.android.job.v14.PlatformAlarmService -keep public class com.evernote.android.job.v14.PlatformAlarmReceiver -keep public class com.evernote.android.job.JobBootReceiver -keep public class com.evernote.android.job.JobRescheduleService -dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement -keep class com.google.android.gms.internal.** { *; } # Moat SDK -keep class com.moat.** { *; } -dontwarn com.moat.**

GDPR 推荐实施方法说明

要使用 Vungle API 来更新或查询用户同意状态(参见“GDPR:推荐实施方法”选项 1 中的推荐),请使用以下函数:

  • // To set the user's consent status to opted in: Vungle.updateConsentStatus(Vungle.Consent.OPTED_IN); // To set the user's consent status to opted out: Vungle.updateConsentStatus(Vungle.Consent.OPTED_OUT); // To find out what the user's current consent status is: // This will return null if the GDPR Consent status has not been set // Otherwise, it will return Vungle.Consent.OPTED_IN or Vungle.Consent.OPTED_OUT UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus(); Vungle.Consent currentStatus = Vungle.getConsentStatus(); 
还有其它问题?提交请求

评论