Migration des Vungle Android SDK from v. 5 to v. 6

Willkommen beim Migrationsleitfaden für Vungle Android SDK v6! Das neue SDK wurde komplett neu programmiert und ist jetzt noch robuster und kompakter. Dieses Dokument führt Sie durch das SDK-Upgrade, da es wichtige Änderungen bei APIs und Integration gibt. Wenn Sie eine völlig neue Integration vornehmen und nicht von v5 SDK migrieren, verwenden Sie statt des vorliegenden Dokumentes den Leitfaden Integration von Vungle Android SDK v6.

In diesem Artikel:

DSGVO: Empfohlene Implementierung

Seit dem 25. Mai gilt in der EU die Datenschutzgrundsatzverordnung (DSGVO). Zur Einhaltung der DSGVO haben Entwickler zwei Optionen.

  • Option 1 (empfohlen): Der Herausgeber steuert den Prozess zur Konformität mit der DSGVO auf Benutzerebene und leitet die Entscheidung des Benutzers an Vungle weiter. Entwickler können dazu die Zustimmung des Benutzers über eigene Mechanismen einholen und dann mit Vungle APIs den Zustimmungsstatus des Benutzers abfragen oder aktualisieren. Einzelheiten finden Sie im Abschnitt Anweisungen zur empfohlenen Implementierung der DSGVO.

  • Option 2: Erlauben Sie Vungle, die Anforderungen zu verwalten. Vungle zeigt europäischen Benutzern vor dem Abspielen einer Werbung einen Zustimmungsdialog an und merkt sich die Zustimmung bzw. Ablehnung des Benutzers für die nachfolgende Werbung.

Bevor Sie anfangen

Highlights der Version

  • Schnell: Initialisierung und Caching sind im Vergleich zu v5 fünfmal schneller
  • Leicht: reduzierte Methodenanzahl
    • Kern-SDK: 750 Methoden
    • Vollständige Integration einschließlich Drittanbieter-Bibliotheken: ca. 4000 Methoden
  • DSGVO-Konformität: Vungle bietet zwei Optionen zum Einholen der Zustimmung des Benutzers: Entweder Vungle oder der Herausgeber können den Prozess steuern. Neue API-Aufrufe wurden hinzugefügt.

Anforderungen

  • Android 4.0 (Ice Cream Sandwich – API-Version 14) oder höher

Beispiel-App

Schritt 1. Das Vungle SDK in Ihrem Projekt ändern

Nutzen Sie abhängig von Ihrer Projektkonfiguration die AAR-Integration über Maven oder JAR zur manuellen Integration.

Option 1. Gradle-Integration

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
}

Fahren Sie fort mit „Schritt 2. Das Vungle SDK importieren

Option 2. JAR-Integration

Laden Sie Vungle SDK v6 herunter und ersetzen Sie das alte Vungle SDK sowie die zugehörigen JAR-Dateien durch das neue SDK und neue Bibliotheken. Achten Sie darauf, erforderliche Bibliotheken zu entfernen bzw. neue hinzuzufügen und zu aktualisieren.

v5-Bibliotheken v6-Bibliothelken
image3.png image2.png

Kompilieren Sie alle JAR-Dateien aus dem heruntergeladenen SDK-Paket.

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. anpassen

<!--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>

Schritt 2. Das Vungle SDK importieren

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

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

Schritt 3. Das Vungle SDK initialisieren

Zum Initialisieren mussten Sie früher zunächst eine Vungle SDK-Instanz verwenden und den init() ausgeben. Diese Methode benötigte Vungle-Anwendungs-ID, String-Array mit Referenz-IDs zur Platzierung und fürVungleInitListener:

// 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) { }
});
}

Die neue Initialisierungsmethode benötigt unterschiedliche Parameter und eine unterschiedliche Reihenfolge:

  • Liste der Strings für die zur Platzierung verwendeten Referenz-IDs
  • Vungle-Anwendungs-ID
  • Anwendungskontext
  • InitCallback
    • onSuccess: meldet die erfolgreiche Initialisierung des SDK
    • onError: meldet eine fehlgeschlagene Initialisierung
      • gibt IllegalArgumentException aus, wenn InitCallback null ist
      • gibt VungleException aus, wenn erforderliche Argumente fehlen oder ungültig sind
    • onAutoCacheAdAvailable: meldet abspielbereite Werbung bei Auto-Cache-Platzierung

onAutoCacheAdAvailablecallback ist als Teil des Initialisierungs-Callbacks verfügbar, da das SDK bei jeder nicht gecachten Werbung versucht, diese in die automatisch gecachte Platzierung zu übernehmen. Dies gilt auch für den erstmaligen Start des SDK oder für zuvor gecachte Werbung, die zur Platzierung abgespielt wurde. Dies bleibt so, bis der Prozess beendet wird oder die Vungle-Instanz als Datenmüll geclaimt wurde. Alle anderen Platzierungen, die nicht automatisch gecacht wurden, loadAd müssen ausdrücklich gemäß der Beschreibung in „Schritt 5. Werbung laden“ erfolgen.

// 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
}
};

Sie können jederzeit überprüfen, ob Vungle SDK initialisiert wurde, indem Sie die isInitialized-Methode aufrufen:

public static boolean isInitialized() 

Schritt 4. Event Listener

Der globale VungleAdEventListener in v5 SDK wurde in SDK v6 durch zwei unabhängige Callbacks ersetzt. Entfernen Sie die VungleAdEventListener-Implementierung für SDK v5 aus Ihrem Projekt:

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

Implementieren Sie LoadAdCallback zum Laden und PlayAdCallback zum Abspielen von Werbung, wenn Sie für alle Ereignisse einen generischen Callback verwenden möchten. Gehen Sie anderenfalls weiter zu „Schritt 5. Werbung laden“, um Inline-Callbacks zu implementieren.

// 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
}
};

Schritt 5. Werbung laden

Das Laden einer Werbung ist in beiden Versionen grundsätzlich gleich, mit der großen Ausnahme, dass in Vungle Android SDK v6 ein lastabhängiger Callback anstatt des vom globalen VungleAdEventListener abhängigen Callbacks in v5 möglich ist. Das LoadAdCallback wird über den Lastzustand des ihm zugewiesenen Aufrufs informiert. Das v6 SDK nimmt diesen Callback nur als Referenz und speichert ihn nicht. Die korrekte Verwaltung des Callbacks liegt in der Verantwortung der aufrufenden Person.

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

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

Das SDK verwaltet den Download der Werbe-Assets zur automatisch gecachten Platzierung, sodass es nicht erforderlich ist, diese Methode für die automatisch gecachte Platzierung zu aktivieren. Bei allen anderen Platzierungen muss die loadAd-Methode aktiviert und erfolgreich ausgeführt werden , bevor das SDK eine Werbung zur Platzierung abspielen kann. Das onAdLoad-Callback wird ausgelöst, wenn dies erfolgt.

// 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) { }
};
}

Schritt 6. Verfügbarkeit der Werbung überprüfen

Die Verfügbarkeitsprüfung entspricht grundsätzlich der von v5 – mit dem Unterschied, dass es sich nun um eine statische Methode statt einer Instanz-Methode handelt.

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

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

Schritt 7. Werbung abspielen

Analog zum Laden von Werbung sind zum Abspielen von Werbung dieselben Angaben wie bei v5 erforderlich, wobei die Option besteht, einen PlayAdCallback an die Methode zu übergeben, der über Erfolg oder Fehlschlag beim Abspielen informiert wird.

// 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)

Sie sollten die Verfügbarkeit von Werbung stets überprüfen, indem Sie die canPlayAd-Methode vor Aktivieren der playAd-Methode aufrufen. Sie müssen sich zudem vergewissern, dass playAd nicht ausgegeben wird, bevor Sie einen onAdEnd oder einen onError-Callback aus dem ursprünglichen playAd-Aufruf erhalten, weil die Werbung nicht korrekt gerendert wird, wenn playAd wiederholt in schneller Folge aufgerufen wird.

// 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) { }
});
}

Schritt 8. Konfigurationsoptionen

Abspieloptionen für Werbung

Die folgende Tabelle zeigt die verfügbaren AdConfig-Optionen.

Option

Beschreibung

setBackButtonImmediatelyEnabled

„true“, wenn die Schaltfläche „Zurück“ vor der Schaltfläche zum Schließen der Werbung aktiviert werden soll, anderenfalls „false“

setFlexViewCloseTime

nimmt einen Integerwert größer oder gleich 0, der die Zeit in Sekunden angibt, in der die Flex-View-Werbung automatisch geschlossen wird

setImmersiveMode

„true“, wenn der immersive Modus für KitKat+-Geräte aktiviert ist, anderenfalls „false“

setAutoRotate

„true“, wenn das Video automatisch gedreht werden soll, „false“, wenn das Video der Ausrichtung der Werbung folgen soll

setMuted

„true“, wenn das Video mit den Audioeinstellungen starten soll, die denen der Anwendung entsprechen, in die es eingebettet ist, „false“, wenn es beim Start stummgeschaltet sein soll

setOrdinal

benötigt einen Integerwert als Nummerierung, um Anzahl der Werbeanzeigen zu erfassen, die in einer Sitzung abgespielt wurde

setTransitionAnimationEnabled

„true“, wenn die Übergangsanimation des Videos aktiviert sein soll, „false“, wenn sie deaktiviert sein soll

Anpassen belohnter Werbung

Der Popup-Dialog für belohnte Werbung konnte in v5 mit dem AdConfig-Objekt konfiguriert werden. In v6 wird jedoch die neue Methode setIncentivizedFields dazu bereitgestellt.

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

Flex-View-Werbung schließen

Flex-View kann programmgesteuert geschlossen werden, indem Sie die closeFlexViewAd-Methode mit der Referenz-ID zur Platzierung ausgeben, mit der aktuell die Flex-View-Werbung abgespielt wird.

public static boolean closeFlexViewAd(@NonNull final String placementReferenceId) 

Liste gültiger Platzierungen

Eine Hilfsmethode, die eine Sammlung von Strings zurückgibt, die alle gültigen Referenz-IDs zur Platzierung für die aktuelle Sitzung enthält.

public static Collection<String> getValidPlacements() 

ProGuard-Richtlinien

# 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.**

Anweisungen zur empfohlenen DSGVO-Implementierung

Bei Verwendung von Vungle APIs zur Aktualisierung oder Abfrage der Benutzerreaktion (wie in Option 1 von DSGVO: Empfohlene Implementierung für Vungle empfohlen), werden folgende Funktionen genutzt:

  • // 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(); 
Haben Sie Fragen? Anfrage einreichen

Kommentare