Erste Schritte mit Vungle SDK v. 5 – Unity

Inhalt

Bevor Sie anfangen

  • Das Vungle Unity Plugin für iOS unterstützt:
    • iOS 8
    • Unity 4 und Unity 5.4.1 oder höher
    • Der Vungle SDK erfordert die Verlinkung des WebKit.framework-Frameworks mit Ihrem Projekt. Wenn Sie für iOS 7 entwickeln, müssen Sie dieses Framework auf „Optional“ setzen. Klicken Sie dazu im Projekt-Navigator auf Ihr Projekt und wechseln Sie zu AllgemeinVerlinkte Frameworks und Bibliotheken. Wählen Sie WebKit.framework aus und setzen Sie den Status auf „Optional“.

  • Das Vungle Unity Plugin für Android:
    • Benötigt Java 1.7 für Android
    • unterstützt Unity 4 sowie Unity 5.3.2 und höher

  • Das Vungle Unity-Plug-in für Windows:
    • Vungle SDK unterstützt derzeit Unity 2017 unter Windows nicht.
    • Windows (Universal 8.1 oder Phone 8.1) unterstützt Unity 4 und Unity 5.3.2+
    • Windows 10 UWP unterstützt Unity 5*.3*.2+
    • Bevor Sie mit dem restlichen Artikel fortfahren, befolgen Sie zunächst die Anweisungen unter „Vorbereiten des Vungle Windows SDK v.2.0+ für das Unity Plugin“. Kehren Sie dann zurück und führen Sie die verbleibenden Schritte durch.

  • Laden Sie unsere Beispiel-App herunter: https://github.com/Vungle/Unity-Plugin/tree/sdk5.

Schritt 1. Richten Sie Ihr Unity Projekt mit dem Vungle Unity Plugin ein

Fügen Sie das Vungle Unity Plugin Ihrem Unity Projekt hinzu

Doppelklicken Sie bei geöffnetem Projekt unter Unity auf die heruntergeladene Datei VunglePlugin.unitypackage, um das Vungle Unity Plugin Ihrer Anwendung hinzuzufügen. Wenn sich das Fenster Unity Paket importieren öffnet, klicken Sie auf alle, um vor dem Import alles auszuwählen.

Adressieren Sie in Ihren Build Settings die richtige Plattform

Um Kompilierungsfehler während des nächsten Schrittes zu vermeiden, müssen Sie überprüfen, ob die Build Settings Ihres Projekts (Cmd + Shift + B) für eine iOS- oder Android-Plattform eingerichtet sind.

Amazon Appstore

Vungle Android SDK unterstützt Amazon OS 5.4 und höher. Sie können Android APK an den Amazon Appstore mit der zusätzlichen Einstellung der Unity Amazon Appstore-Konfiguration übermitteln. Die Unity-Anleitungen finden Sie hier.

Google Play Services

Wenn Sie Google Play-Dienste in Ihr Projekt integrieren, kann Vungle besser auf die Endbenutzer zugeschnittene Werbung bereitstellen. Dies ist aber nicht zwingend erforderlich. Wir empfehlen Version 11.0.1 oder höher.

Zur Integration der Google Play Services empfehlen wir Google's Setup Guide. Stellen Sie in Ihrer App sicher, dass das Gerät über eine hinreichend aktuelle Version von Google Play Services verfügt. Das Vungle SDK verwendet optional die API Location and Ads von Google Play Services.

  • android.gms:play-services-location:11.0.1
  • android.gms:play-services-ads:11.0.1
  • Bei play-services 7.8.0 und älter: Die Support-Bibliothek beibehalten
  • Für Play Services 8.4.0 und höher: Die Support-Bibliothek ist nicht erforderlich.

Wir haben unser eigenständiges SDK zur Kompilierung mit den folgenden Versionen von Google Play Services erfolgreich erstellt: 7.8.0, 8.4.0, 9.8.0, 10.2.4 und 11.0.1.

Nachdem Google Play Services hinzugefügt wurde, geben Sie die folgenden Berechtigungen in AndroidManifest.xml ein. Anhand dieser Informationen optimiert Vungle die Anzeige für den Nutzer:

  • <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  • <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Schritt 2: Fügen Sie Programmcode ein

In dieser Anleitung initialisieren wir alle, den Vungle-betreffenden Code in einem Skript, das dem Haupt-Spiel-Objekt beigefügt ist. Sie können das Vungle Unity Plugin von allen Skripten aus rufen, die sie als geeignet ansehen.

Initialisieren Sie das SDK

Hinweis: Eine Standard-Platzierung wird automatisch für jede App erstellt. Sie müssen die Referenz-ID dieser Platzierung in diesem Initialisierungsschritt bereitstellen, auch wenn Sie nicht von der Platzierungs-Funktion Gebrauch machen möchten. Bei der Erstellung mehrerer Platzierungen müssen Sie alle Referenz-IDs angeben.

Initialisieren Sie das SDK, sobald Ihre App startet, damit dem SDK ausreichend Zeit zum Cachen einer Werbung für die automatisch gecachte Platzierung bleibt. Um das SDK zu initialisieren, benötigen Sie:

  • Alle App-IDs für alle Plattformen, die Sie unterstützen möchten
  • Alle Platzierungsreferenz-IDs, die Sie in Ihrer App verwenden möchten, für alle Plattformen (sowohl aktive als auch inaktive)

Diese IDs finden Sie im Vungle Dashboard (sehen Sie im Abschnitt Einrichtung von und Berichte über Platzierungen nach).

Beispielcode:

public class VungleScript : MonoBehaviour { string appID = "";
string iosAppID = "ios_app_id";
string androidAppID = "android_app_id";
string windowsAppID = "windows_app_id"; #if UNITY_IPHONE appID = iosAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "ios_placement_id_1", false }, { "ios_placement_id_2", false }, { "ios_placement_id_3", false } }; #elif UNITY_ANDROID appID = androidAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "android_placement_id_1", false }, { "android_placement_id_2", false }, { "android_placement_id_3", false } }; #elif UNITY_WSA_10_0 || UNITY_WINRT_8_1 || UNITY_METRO appID = windowsAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "windows_placement_id_1", false }, { "windows_placement_id_2", false }, { "windows_placement_id_3", false } }; #endif string[] array = new string[placements.Keys.Count]; placements.Keys.CopyTo(array, 0); Vungle.init(appID, array);
}

Sobald das SDK erfolgreich initialisiert wurde, ruft es das folgende Event auf:

public static event Action onInitializeEvent;

Sehen Sie im Abschnitt "Event-Handling" dieses Artikels nach.

Nachdem das Vungle SDK initialisiert wurde, fordert es automatisch eine Werbung für die Platzierung, die Sie im Vungle Dashboard als automatisch gecacht ausgewählt haben. Wir empfehlen, die am häufigsten betrachtete Platzierung zum automatischen Cachen auszuwählen.

Sobald eine Werbung erfolgreich gecacht wurde, wird das Event adPlayableEvent mit der Referenz-ID der Platzierung aufgerufen, die zu Ihrer automatisch gecachten Platzierung passt. (Sehen Sie im Abschnitt "Werbungsverfügbarkeit für eine Platzierung prüfen" dieses Artikels nach.)

Laden einer Werbung für eine Platzierung

Für alle weiteren Platzierungen neben der automatisch gecachten Platzierung, rufen Sie die loadAd-Methode, um eine Werbung zu laden.

public static void loadAd(string placementID)

Stellen Sie sicher, dass Sie die placementID verwenden, die mit der richtigen Plattform verknüpft ist.

Beispielcode:

string placementID; #if UNITY_IPHONE placementID = "ios_placement_id"; #elif UNITY_ANDROID placementID = "android_placement_id"; #elif UNITY_WSA_10_0 || UNITY_WINRT_8_1 || UNITY_METRO placementID = "windows_placement_id"; #endif Vungle.loadAd(placementID);

Prüfen der Werbungsverfügbarkeit für eine Platzierung

Sobald das SDK erfolgreich eine Werbung für eine Platzierung gecacht hat, wird das folgende Event aufgerufen:

public static event Action<string, bool> adPlayableEvent;

Beispielcode:

Vungle.adPlayableEvent += (placementID, adPlayable) => { if(placementID == ) { layButtonPlacement1.enabled = adPlayable; } };

Hinweis: Für die automatisch gecachte Platzierung wird dieses Event nur gerufen, wenn eine Werbung verfügbar wird. Das SDK fordert weiterhin eine Werbung zur automatisch gecachten Platzierung an. Bei allen anderen Platzierungen wir das Event auch im Fall von "Load Failed" aufgerufen ((adPlayable) gibt in diesem Fall "NO" zurück).

Sie können die Werbungsverfügbarkeit für eine Platzierung auch mit der folgenden Methode prüfen:

public static bool isAdvertAvailable(string placementID);

Abspielen einer Werbung

Wichtig: Spielen Sie keine Werbung ab, bevor die oben beschriebene adPlayableEvent-Funktion wieder den Wert „true“ angenommen hat. Wenn Sie Werbung abspielen, bevor adPlayableEvent wieder „true“ ist, wird beim Versuch, die Werbung zu laden, die Systemleistung des Benutzers beeinträchtigt.

Nachdem eine Werbung zur Platzierung bereitsteht, können Sie sie über die folgende Methode abspielen:

public static void playAd(string placementID);

Beispielcode:

Vungle.playAd ();

Event Handling

Event Handler können für alle 5 Vungle SDK Events eingerichtet werden, die die Werbepräsentation betreffen.

  • Folgendes Ereignis wird ausgelöst, wenn das SDK ein Werbevideo wiedergibt. Dies ist eine gute Gelegenheit, um Spiele, Audioeffekte, Animationen usw. pausieren zu lassen.
    public static event Action onAdStartedEvent;
  • Folgendes Ereignis wird ausgelöst, wenn das SDK ein Werbevideo schließt. Dies ist eine gute Gelegenheit, Ihren Nutzer zu belohnen und die Wiedergabe von Spielen, Audioeffekten, Animationen etc. wiederaufzunehmen.
    public static event Action<string, AdFinishedEventArgs> onAdFinishedEvent;

    Die Klasse AdFinishedEventArgs besitzt folgende Eigenschaften, mit denen Sie das Ergebnis einer abgespielten Werbeanzeige überprüfen können:
    public class AdFinishedEventArgs : EventArgs { //Represents a BOOL whether or not the user clicked the download button. public bool WasCallToActionClicked{ get; set;} //Represents a bool whether or not the video can be considered a completed view. public bool IsCompletedView{ get; set;} }
  • Folgendes Ereignis wird ausgelöst, wenn das SDK den Verfügbarkeitsstatus der Werbung geändert hat. Der isAdPlayable-Boolean gibt die neue Wiedergabebereitschaft einer bestimmten placementID an.
    public static event Action<string, bool> adPlayableEvent;
    Weitere Details finden Sie im Abschnitt „Werbeanzeigen-Verfügbarkeit für eine Platzierung überprüfen“.

  • Folgendes Ereignis wird ausgelöst, wenn das SDK erfolgreich initialisiert wurde.
    public static event Action onInitializeEvent;
  • Folgendes Ereignis wird ausgelöst, wenn das SDK Protokolle ausgibt.
    public static event Action onLogEvent;

Beispielcode:

void initializeEventHandlers() { Vungle.onAdStartedEvent += (placementID) => { DebugLog ("Ad " + placementID + " is starting! Pause your game animation or sound here."); }; Vungle.onAdFinishedEvent += (placementID, args) => { DebugLog ("Ad finished - placementID " + placementID + ", was call to action clicked:" + args.WasCallToActionClicked + ", is completed view:" + args.IsCompletedView); }; Vungle.adPlayableEvent += (placementID, adPlayable) => { DebugLog ("Ad's playable state has been changed! placementID " + placementID + ". Now: " + adPlayable); }; Vungle.onLogEvent += (log) => { DebugLog ("Log: " + log); }; Vungle.onInitializeEvent += () => { adInited = true; DebugLog ("SDK initialized"); }; }

OnPause and OnResume Functionality

Fügen Sie Programcode für die onPause- und onResume-Funktionalität ein, die Werbungen zum Weiterspielen aktiviert, nachdem sie durch eine in den Hintergrund getretene App gestoppt worden waren.

void OnApplicationPause(bool pauseStatus) { if (pauseStatus) { Vungle.onPause(); } else { Vungle.onResume(); } }

Anpassungsoptionen

Die playAd-Methode kann außerdem eine Liste verfügbarer Optionen annehmen, mit dem das Abspielerlebnis angepasst werden kann.

public static void playAd(Dictionary<string,object> options, string placementID);

Hinweis: Belohnte Anzeigen (rewarded ads) werden im Englischen auch manchmal als incentivized bezeichnet; beide Begriffe stehen für dieselbe Art von Werbeanzeige. Im SDK-Code und in unserer Reporting-API verwenden wir den Begriff „incentivized”.

Das Verzeichnis der verfügbaren Optionen nimmt die folgenden Schlüsselwörter an:

Schlüssel

Beschreibung

orientation

Legt die Ausrichtung der Werbung fest.

  • Für iOS verwenden Sie VungleAdOrientation:
    public enum VungleAdOrientation { Portrait = 1, LandscapeLeft = 2, LandscapeRight = 3, PortraitUpsideDown = 4, Landscape = 5, All = 6, AllButUpsideDown = 7 }
  • Für Android verwenden Sie "true" für matchVideo und "false" für autoRotate.

userTag

Der User-Key wird bei einem Server-zu-Server-Aufruf (falls vorhanden) zur Identifizierung von Nutzern übergeben.

alertTitle

Zeichenfolge, die als Titel des Warndialogfelds verwendet wird, das angezeigt wird, wenn ein Benutzer eine Werbung mit Belohnungsanreiz vorzeitig schließt.

alertText

Zeichenfolge, die als Text des Warndialogfelds verwendet wird, das angezeigt wird, wenn ein Benutzer eine Werbung mit Belohnungsanreiz vorzeitig schließt.

closeText

Zeichenfolge, die als Beschriftung der Schaltfläche „Schließen" in dem Warndialogfeld verwendet wird, das angezeigt wird, wenn ein Benutzer eine Werbung mit Belohnungsanreiz vorzeitig schließt.

continueText

Zeichenfolge, die als Beschriftung der Schaltfläche „Schließen" in dem Warndialogfeld verwendet wird, das angezeigt wird, wenn ein Benutzer eine Werbung mit Belohnungsanreiz vorzeitig schließt.

immersive

Den immersiven Modus für Android einschalten.

flexCloseSec

Die ist nur für iOS verfügbar und bezeichnet die Anzahl an Sekunden, nach deren Ablauf die Flex View-Werbung automatisch geschlossen werden kann. Die gilt nur für Flex View (nicht für Flex Feed)-Werbung und nur für iOS.

 

Flex Feed-Werbung

Für iOS

Verwenden Sie zum programmgesteuerten Schließen einer Flex View-Werbung die Funktion „closeAd“:

Vungle.closeAd(placementIdList[1]);

Diese Funktion ist nicht für Android nutzbar.

Für Android

Flex View funktioniert in Unity Android anders als in Unity iOS oder nativem Android. Dies liegt an einer Einschränkung von Unity beim Handling von Aktivitäten, Flex View erlaubt dem Benutzer keine Interaktion mit dem Basisspiel, während eine Flex View-Werbung angezeigt wird. In einer Flex View-Werbung wird die zugrunde liegende Aktivität beendet und eine neue Aktivität darüber angezeigt. Wenn ein Benutzer nun eine App verlässt, während eine Flex View-Werbung angezeigt wird und er später wieder zu dieser App zurückkehrt, dann wird die Werbung zwar angezeigt, das im Hintergrund ausgeführte Spiel bleibt hingegen schwarz. Dies passiert, weil die Basisanwendung unterbrochen wird, bis die Flex View-Werbung geschlossen wird.

Vermeiden Sie daher Flex View-Werbung in Unity Android.

Haben Sie Fragen? Anfrage einreichen

Kommentare