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

本文介绍如何集成 Vungle 的 Android SDK 或 Amazon SDK。从 Android SDK v.5.3.0 开始,Vungle 支持 Amazon OS 5.4 及更高版本。Amazon SDK 的集成步骤与 Android 相同,只是 Amazon 集成需要使用 Amazon 应用程序 ID。

本文内容:

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)或更高版本
  • Android 支持库 v26 或更高版本
  • Android targetSdkVersion 26 或更低版本

示例应用程序

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

Vungle SDK 可通过两种方式获取:AAR(通过 Maven)文件,或 JAR 集成。

选项 1:AAR 集成

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

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

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

dependencies { … // Vungle SDK
compile 'com.github.vungle:vungle-android-sdk:6.2.5'
// Optional Google Play Services - Location and Basement
compile 'com.google.android.gms:play-services-basement:11.0.4'
compile 'com.google.android.gms:play-services-location:11.0.4' … }

如果已添加 Vungle SDK(通过 Maven),则可跳过“步骤 2:导入 Vungle SDK”。

选项 2:JAR 集成

  1. 下载 Vungle SDK v. 6并解压,然后进入 libs 文件夹,复制所有 jar 文件,并将其添加到项目的 libs 文件夹中。

    Screen_Shot_2018-08-16_at_7.14.46_AM.png
  2. 打开项目级别的 build.gradle,然后更新“repositories”部分。

    allprojects {
    repositories {
    jcenter()
    }
    }
  3. 打开应用程序级别的 build.gradle 文件,并在“dependencies”部分添加其他依赖项。

    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 // Support libraries compile 'com.android.support:support-v4:26.0.1' … } 
  4. 如果手动添加 Vungle SDK,请继续执行“步骤 2:导入 Vungle SDK”。

  5. 更新 AndroidManifest.xml:将以下几行添加到您的 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" />

    <!--Optional Permissions-->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!--Vungle Activities-->
    <activity
    android:name="com.vungle.warren.ui.VungleActivity"
    android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
    android:launchMode="singleTop"
    android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />
    <activity
    android:name="com.vungle.warren.ui.VungleFlexViewActivity"
    android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
    android:hardwareAccelerated="true"
    android:launchMode="singleTop"
    android:theme="@android:style/Theme.Translucent.NoTitleBar" />

步骤 2:导入 Vungle SDK

import com.vungle.warren.Vungle; import com.vungle.warren.AdConfig; // Custom ad configurations import com.vungle.warren.InitCallback; // Initialization callback import com.vungle.warren.LoadAdCallback; // Load ad callback import com.vungle.warren.PlayAdCallback; // Play ad callback import com.vungle.warren.VungleNativeAd; // Flex-Feed ad

步骤 3:初始化 Vungle SDK

初始化方法采用以下参数:

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

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

Vungle.init(appId, 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.getLocalizedMessage() 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. Otherwise, please use // LoadAdCallback with loadAd API for loading placements. } };

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

public static boolean isInitialized()

步骤 4:事件侦听器

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

// Implement 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 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:加载广告

在 Vungle Android SDK v6 中,允许按负载回调,而不是像 v5 那样依靠全局 VungleAdEventListenerLoadAdCallback 会获得有关所分配调用的负载状态的通知。v6 SDK 仅引用此回调且不会将其存储在任何地方;调用方应确保对回调的妥善管理。

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

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

// 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) {
// Load ad error occurred - throwable.getLocalizedMessage() contains error message
}
};
}

步骤 6:检查广告可用性

使用静态方法 canPlayAdmethod 检查相应广告位置上在调用 playAd() method 之前是否有可播放的广告。

public static boolean canPlayAd(@NonNull String id)

步骤 7:播放广告

播放广告时,需要调用 playAd 方法,其中包含广告位置参考 ID、可选 AdConfig(如果未使用,则为空)以及 PlayAdCallback 事件侦听器(用于在广告播放期间接收播放成功或出错的通知)。

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

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

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) {
// Play ad error occurred - throwable.getLocalizedMessage() contains error message
}
});
}

发生 onError 时重新初始化 SDK

在极少数情况下,可能因为资源有限而导致系统释放一部分 Vungle SDK 或者 SDK 所需的某些第三方依赖项。在这种情况下,LoadAdCallback and PlayAdCallback 将触发一个 onError() 回调,其中包含带有 ‘VungleException.VUNGLE_NOT_INTIALIZED’ 代码的可抛出对象。这表明 Vungle SDK 处于不可操作状态,必须对其重新初始化。

@Override public void onError(String placementReferenceID, Throwable throwable) { try { VungleException ex = (VungleException) throwable; if (ex.getExceptionCode() == VungleException.VUNGLE_NOT_INTIALIZED) { initializeVungleSDK(); } } catch (ClassCastException cex) { Log.d(LOG_TAG, cex.getMessage()); } } 

Native Flex 广告

Flex-View 广告

Flex-View 广告可以像普通全屏广告一样加载和播放。只需从管理面板中调用广告位置类型为“Flex-View”的广告位置参考 ID 即可。

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

public static boolean closeFlexViewAd(@NonNull final String placementReferenceId)

另一个方法是在 Flex-View 广告播放了指定时间段后自动关闭,详情参阅“广告配置选项”部分。

Flex-Feed 广告

Flex-Feed 广告格式不需要全屏显示;相反,发布商可在其应用程序中确定广告容器的确切尺寸和位置。这些广告容器可以采用集合视图或表格/列表视图查看。

加载 Flex-Feed 广告

发布商必须加载适用于 Flex-Feed 容器和广告。加载 Flex-Feed 广告与加载全屏或插屏式广告的方法相同;但是,必须将广告位置配置为支持 Flex-Feed。请联系您的 Vungle 客户经理来为广告位置启用 Flex Feed。

显示 Flex-Feed 广告

显示 Flex-Feed 广告与显示全屏广告不同。使用 Flex-Feed 广告,您必须先为广告创建容器。此容器是一个 Layout。您可以将上述 RelativeLayout 放在屏幕上的任何位置。广告将缩放到任何尺寸的容器中,但是请记住,如果分辨率非常低,广告可视度会比较低。然后您必须调用 Vungle.getNativeAd 来获取 Flex-Feed 广告对象并调用 addView 函数来将此容器与 Flex-Feed 广告关联。

private RelativeLayout flexfeed_container = findViewById(...); VungleNativeAd vungleNativeAd = Vungle.getNativeAd("FLEXFEED_ID", vunglePlayAdCallback); View nativeAdView = vungleNativeAd.renderNativeView(); flexfeed_container.addView(nativeAdView); 

关闭 Flex-Feed 广告

由于 Flex-Feed 广告视图已添加到容器视图中,因此如果出现广告视图从屏幕上消失、Activity 或片段被销毁、或父视图容器被回收或销毁等情形,则必须将其移除。如不关闭广告,此类事件会导致应用程序出现意外行为。

private VungleNativeAd vungleNativeAd; // Calling finishDisplayingAd when you want to finish displaying Flex-Feed Ad will  会触发 onAdEnd,并会告诉您移除子 FlexFeed 视图容器的时机
vungleNativeAd.finishDisplayingAd(); // And removing empty ad view from container @Override public void onAdEnd(String id, boolean completed) { … parentView.remove(nativeAdView); vungleNativeAd = null; … }

附加和分离 Flex-Feed 广告的状态

如果用户滚动屏幕到视频广告已不可见的位置,发布商必须暂停该视频,并在视频再次可见时继续播放。要控制视频的暂停和继续播放状态,请从 VungleNativeAd 实例调用 setAdVisibility(),并将其设置成视频可见时为“true”,视频从屏幕上消失时为“false”。setAdVisibility 不应与视图可见性混为一谈:该设置程序会向 Vungle SDK 通知原生广告视图是否可见,而 SDK 会据此来暂停/继续播放视频。

要暂停 Flex-Feed 广告:

vungleNativeAd.setAdVisibility(false);

要继续播放 Flex-Feed 广告:

vungleNativeAd.setAdVisibility(true);

高级设置

Google Play Services(可选)

在项目中添加 Google Play Services 之后,Vungle 即可为终端用户提供更加个性化的广告体验。Google Cloud Messaging 是必需的 API,而 Google Location and Activity Recognition 以及 Google Location and Basement API 是可选项。我们建议使用 11.0.1 或更高版本。

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

  • google.android.gms:play-services-basement:15.0.1 // 必需
  • google.android.gms:play-services-ads-identifier:15.0.1 // 推荐
  • google.android.gms:play-services-location:15.0.1 // 推荐

减少方法数量

在项目中添加 Vungle Android SDK v6 会增加大约 750 个核心 Vungle 方法(不包括任何传递性依赖)。完整集成(含第三方库)预计平均增加不到 4000 个方法。请考虑以下建议以减少在项目中添加的方法总数。

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

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

Proguard

如果正在使用 Proguard,请在 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.**

UI 线程注释

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

广告配置选项

广告配置

您可以选择向 playAd 提供新的 adConfig 对象来定制每条广告。AdConfig 对象可以为空,此时广告将采用默认配置进行播放,该对象也可以不为空,则此时会覆盖 AdConfig 设置程序。以下示例介绍了如何使用 AdConfig

Vungle.playAd(placementReferenceID, null, vunglePlayAdCallback);

上例中的 adConfig 对象设为 null;如果不想设置任何其他配置,则可以执行此操作。如下所示使用 AdConfig 对象:

AdConfig adConfig = new AdConfig(); adConfig.setAutoRotate(true); adConfig.setMuted(true); Vungle.playAd(placementReferenceID, adConfig, vunglePlayAdCallback);

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

选项

说明

setBackButtonImmediatelyEnabled

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

setFlexViewCloseTime

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

setImmersiveMode

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

setAutoRotate

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

setMuted

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

setOrdinal

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

setTransitionAnimationEnabled

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

您可以为多个广告位置参考 ID 使用相同的 AdConfig 对象。

其他奖励式广告配置

您可使用 Vungle 对象来进行奖励式视频设置。

选项

说明

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

当用户尝试关闭奖励式视频时,屏幕上会弹出窗口以确认用户的操作。您可以使用此设置来定制弹出窗口。如果不想修改默认值时可使用 null(例如,您只想更改用户 ID)。

如下所示设置奖励式广告配置:

Vungle.setIncentivizedFields("user1","title1","body1","keepwatching1","close1"); Vungle.playAd("YOUR_APP_ID", AdConfig, vunglePlayAdCallback);

有效广告位置列表

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

public static Collection getValidPlacements()

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: Vungle.Consent currentStatus = Vungle.getConsentStatus(); 

硬件加速

如果将目标 API 级别设置为 14 或以上,则默认启用硬件加速。必须启用此选项才能使 SDK 正确显示 Dynamic Template 和 Native Flex 广告。请确保此选项在您的项目中已设置为“true”:

<application android:hardwareAccelerated="true" ...>

检索 SDK 版本号

要通过编程方式检索运行时的 SDK 版本号(这在内部协调时很有用),Vungle 提供了以下字符串:

com.vungle.warren.BuildConfig.VERSION_NAME

补充说明

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
这篇文章有帮助吗?
2 人中有 1 人觉得有帮助