Vungle Android SDK v. 5 を v. 6 に移行する

これは、Vungle Android SDK v6 の移行ガイドです。新しい SDK は、安定性と軽量性の両方を実現するため、全面的に更新されています。新しい SDK では、API と統合機能が大きく変更されているため、このガイドで、新しい SDK にアップグレードするための手順について説明します。SDK v5 から SDK v6 に移行するのではなく、新しい統合環境を使用する場合は、このガイドではなく、Vungle Android SDK v6 の統合ガイドを参照してください。

この記事では、以下の項目について説明します。

EU 一般データ保護規則 (GDPR) に準拠するための推奨事項

5 月 25 日より、欧州連合で一般データ保護規則 (GDPR) が施行されました。開発者は、以下に示すいずれかの方法で GDPR に準拠する必要があります。

  • 方法 1 (推奨): パブリッシャーが、ユーザー レベルで GDPR 同意プロセスを管理し、ユーザーによる選択内容を Vungle に伝える。これを行うには、開発者が独自のメカニズムを使用してユーザーから同意を取得し、Vungle API を使用して、ユーザーの同意状況の更新や照会を実行します。詳しくは、「GDPR に準拠するための推奨手順」を参照してください。

  • 方法 2: 広告を表示するための要件の処理を Vungle に委任する。この方法の場合、欧州のユーザーに広告を表示する前に、同意ダイアログが表示されます。それ以降は、ユーザーが広告の表示に同意したか拒否したかがシステムに記憶されることになります。

はじめに

本リリースのハイライト

  • 高速: 初期化処理とキャッシュ処理の速度が、v5 と比較して最大 5 倍にまで上がりました。
  • 軽量: メソッドの数が削減されました。
    • コア SDK: 750 のメソッド
    • サードパーティ製ライブラリを含む完全な統合: 最大 4000 のメソッド
  • GDPR への準拠: 2 つの方法でユーザーの同意を得ることができます。このプロセスは、Vungle が管理することも、パブリッシャーが管理することもできます。これに伴い、新しい API 呼び出しが導入されました。

要件

  • Android 4.0 (Ice Cream Sandwich - API version 14) またはそれ以降

サンプル アプリケーション

手順 1. プロジェクト内で Vungle SDK を変更する

プロジェクトの設定内容に応じて、Maven 経由での AAR 統合を使用するか、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 が null の場合に IllegalArgumentException をスローする
      • 必須の引数が指定されていない (または正しくない) 場合に、VungleException をスローする
    • onAutoCacheAdAvailable: 自動的にキャッシュされた配置広告に再生可能な広告が含まれている場合に通知する

広告が事前にキャッシュされていない場合、SDK は自動的にキャッシュされる配置広告に対して継続的に広告をキャッシュしようとするため、初期化コールバックの一環として onAutoCacheAdAvailablecallback を使用することができます。たとえば、SDK を初めて起動する場合や、配置用に事前にキャッシュされた広告を再生する場合などに使用することができます。この動作は、実行中のプロセスが停止するまで、またはガベージ コレクションによって 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 v6 では、SDK v5 で使用されていたグローバルな VungleAdEventListener が、読み込みイベントと再生イベントで使用される独立した 2 つのコールバックに置き換えられました。そのため、以下のように、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. 広告を読み込む

v5 と v6 の両方で、広告の読み込み方法は基本的に同じです。ただし、大きな違いとして、v5 ではグローバルな VungleAdEventListener が使用されていましたが、v6 では、広告を読み込むたびにコールバックを実行できるようになりました。割り当てられているコールバックについて、広告の読み込み状況が LoadAdCallback に通知されます。v6 の SDK は、このコールバックだけを参照します。このコールバックはどこにも保存されないため、呼び出し側で、このコールバックを適切に管理する必要があります。

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

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

自動キャッシュ配置用の広告アセットのダウンロードは SDK によって管理されるため、自動キャッシュ配置用にこのメソッドを呼び出す必要はありません。それ以外のすべての配置広告については、SDK で配置用の広告を再生できるように、loadAd メソッドを呼び出して正しく実行する必要があります。このメソッドを呼び出すと、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. 広告の状況を確認する

v6 で広告の状況を確認する方法は、基本的には v5 の場合と同じですが、インスタンス メソッドではなく静的なメソッドが使用される点だけが異なっています。

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

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

手順 7. 広告を再生する

広告の読み込み方法が変更されたのと同様に、v6 で広告を再生する場合も、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 を短時間に続けて呼び出すと広告が正しくレンダリングされないため、最初に呼び出した playAd から onAdEnd コールバックまたは onError コールバックを受け取る前に、別の 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.**

EU 一般データ保護規則 (GDPR) に準拠するための推奨手順

EU 一般データ保護規則 (GDPR) に準拠するための推奨事項」セクションの「方法 1」で説明したように、Vungle API を使用して、ユーザーの同意状況の更新や照会を行うことをお勧めします。そのためには、以下の関数を使用します。

  • // 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(); 
他にご質問がございましたら、リクエストを送信してください

コメント