Erste Schritte mit Vungle – Adobe Air

Anweisungen zur Adobe Air-Erweiterung

Bevor Sie beginnen:

  • Die Vungle-Erweiterung erfordert Adobe AIR SDK 4.0 oder höher. Anweisungen zur Aktualisierung von SDK in Flash Builder oder Flash Professional, finden Sie unter dem Link „Wie aktualisiere ich AIR SDK?” am Ende dieser Leitfadens.>

  • Wenn Sie mit Android arbeiten, erfordert die Vungle AIR-Erweiterung die Installation von JDK 7 auf dem Entwicklungssystem.

  • Sie können sich die ActionScript 3 Klassenbibliothek anzeigen lassen.

  • Lesen Sie 'example/VungleExample.as', um eine beispielhafte Anwendungsklasse zu erhalten. (Wenn Sie Flash Professional verwenden und nicht sicher sind, wie eine Dokumentenklasse verwendet wird, lesen Sie „Wie verwende ich die VungleBeispiel-Dokumentenklasse in Flash CS6?” am Ende dieser Leitfadens.)

1. Erfassen der Erweiterungsbibliothek

Erstellen Sie zunächst ein neues AIR for mobile-Projekt und fügen Sie die native Erweiterung hinzu.

Wenn eine Verwendung in Androidvorgesehen ist: möglicherweise müssen die Google Play-Dienste und/oder die Android v4-Support-Bibliothek zu Ihrem Projekt hinzugefügt werden. Zahlreiche weitere Erweiterungen umfassen bereits diese Bibliotheken, sodass diese möglicherweise nicht mehr hinzugefügt werden müssen. Um die Erweiterungen hinzuzufügen, wiederholen Sie die untenstehenden Schritte und verwenden com.vungle.extensions.android.GooglePlayServices.ane und/oder com.vungle.extensions.android.AndroidSupportLib.ane anstelle von com.vungle.extensions.Vungle.ane.

In Flash Professional CS6 oder höher:

  1. Erstellen Sie ein neues AIR for Android-Projekt oder AIR for iOS-Projekt
  2. Wählen Sie File > Veröffentlichungseinstellungen...
  3. Wählen Sie das Schraubenschlüsselsymbol, das sich gleich neben ,Skript‘ für ,ActionScript-Einstellungen‘ befindet
  4. Wählen Sie die Registerkarte für den Bibliothekspfad
  5. Klicken Sie auf ,Nach nativen Erweiterungsdateien (ANE) suchen‘ und wählen Sie die Datei com.vungle.extensions.Vungle.ane. Drücken Sie OK
  6. Wählen Sie das Schraubenschlüsselsymbol, das sich gleich neben ,Ziel‘ für Player-Einstellungen befindet
  7. Wenn eine Verwendung in Androidvorgesehen ist: Wählen Sie die Registerkarte ,Zugriffe‘ und aktivieren Sie ,INTERNET', ,WRITE_EXTERNAL_STORAGE', und ,ACCESS_NETWORK_STATE'
  8. Markieren Sie die Schaltfläche ,Zugriffe manuell verwalten und Ergänzungen für diese App anzeigen‘
  9. Drücken Sie OK

In Flash Builder 4.6 oder höher:

  1. Gehen Sie zu Projekteigenschaften
  2. Wählen Sie Native Erweiterungen unter Actionscript Build-Pfad
  3. Wählen Sie Add ANE... und navigieren Sie zur Datei com.vungle.extensions.Vungle.ane
  4. Wählen SieActionscript Build-Paket > Google Android
  5. Wählen Sie die Registerkarte Native Erweiterungen und klicken Sie auf das Kontrollkästchen ,Paket', das sich gleich neben der Erweiterung befindet.
  6. Wenn die Verwendung in iOS vorgesehen ist, wiederholen Sie die Schritte 4 und 5 für das ,Apple iOS-Ziel‘

2. Aktualisierung Ihres Application Descriptors

Damit Vungle funktioniert, sind Änderungen an der XML-Anwendungsdatei Ihrer Anwendung erforderlich. Nehmen Sie folgende Änderungen der mit von Ihrer IDE erstellten XML-Datei vor (Wenn Sie Flash Professional verwenden, überprüfen Sie, ob Sie die oben genannten Schritte zur ,Erfassung der Bibliothek in Flash Professional CS6 oder höher‘ durchgeführt haben. Ansonsten werden Ihre Änderungen möglicherweise von Flash verworfen, während Sie diese vornehmen):

  1. Stellen Sie Ihre AIR-SDK in der App Descriptor-Datei auf 4.0 (oder höher):

    <application xmlns="http://ns.adobe.com/air/application/4.0">
  2. Fügen Sie einen Link zur Erweiterung des Descriptors hinzu:

    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    </extensions>
  3. Wenn die Verwendung in Android vorgesehen ist: möglicherweise müssen Sie die Google Play-Dienste und/oder die Android Support Lib-Erweiterungen hinzufügen. Geben Sie hier auch die Erweiterungs-IDs ein.

    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    <extensionID>com.vungle.extensions.android.AndroidSupportLib</extensionID>
    </extensions>

Für AIR-Applikationen unter Verwendung von Android

Wenn die Verwendung in Android vorgesehen ist, aktualisieren Sie die Manifest-Ergänzungen für Android im XML-Element für Android, um die Zugriffe INTERNET, WRITE_EXTERNAL_STORAGE, und ACCESS_NETWORK_STATE einzubeziehen; fügen Sie die Definition der Aktivität FullScreenAdActivity hinzu; fügen Sie den Dienst VungleService hinzu; und fügen Sie Metadaten-Elemente der Version der Google Play-Dienste hinzu:

<android> 
<manifestAdditions><![CDATA[ 
<manifest android:installLocation="auto"> 

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

  <application>
    <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>

    <activity
      android:name="com.vungle.publisher.FullScreenAdActivity"
      android:configChanges="keyboardHidden|orientation|screenSize"
      android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
    />

    <service android:name="com.vungle.publisher.VungleService"
      android:exported="false"
    />
  </application> 
</manifest> 
]]></manifestAdditions>
</android>

3. Integrieren Sie die Vungle-API

Die Vungle-API kann mit nur wenigen Zeilen von ActionScript zu Ihrer Anwendung hinzugefügt werden.

Initialisierung der Vungle Extension

Initialisierten Sie API, wenn Ihre Anwendung gestartet wird. (Bei der Verwendung von ActionScript geschieht dies im Konstruktor Ihrer Dokumentenklasse. Bei der Verwendung mit Flex geschieht dies im initialize()-Ereignis der Hauptklasse. Bei der Verwendung eines Zeitlinien-Codes in Flash, geschieht dies in Frame 1.)

  1. Importieren der API-Klassen:

    import com.vungle.extensions.*; 
    import com.vungle.extensions.events.*;
  2. Initialisieren Sie die API durch Aufrufen von Vungle.create()m und Hinzufügen eines Arrays mit Ihrer Anwendungs-ID aus dem Vungle Dashboard. Wenn die Verwendung sowohl in iOS als auch in Android innerhalb desselben Projekts vorgesehen ist, müssen beide IDs in das Array einbezogen werden – erst die iOS-ID und als Zweite dann die Android-ID.

    Der Abruf von Vungle.create() sollte in einer Try/Catch-Anweisung erfolgen, da Vungle während des Erstellungsvorgangs möglicherweise einen Fehler meldet (z. B. wenn die auf dem Desktop laufende Erweiterung einen Fehler meldet):

    try
    { 
      // Initialisierung mit Ihrer App-ID 
      Vungle.create(["your_vungle_id"]); 
    
      // -ODER- Initialisierung multiplattformfähiger Anwendungen mit iOS-ID und Android-ID 
      // Vungle.create(["your_ios_vungle_id","your_android_vungle_id"]); 
    } catch (error:Error) {
      // Erweiterung konnte nicht erstellt werden. Läuft die Anwendung auf etwas außer iOS/Android?
    }

Display an Interstitial Ad

Um ein Interstitial-Werbevideo anzuzeigen, rufen Sie playAd() ab. Möglicherweise möchten Sie mit der isAdAvailable()-Methode zunächst überprüfen, ob die Anwendung verfügbar ist:

if (Vungle.vungle.isAdAvailable())
{
    Vungle.vungle.playAd();
}

Display an Incentivized Ad

Um ein Werbevideo mit Anreiz anzuzeigen, rufen Sie displayIncentivizedAd() ab. Möglicherweise möchten Sie mit der isAdAvailable()-Methode zunächst überprüfen, ob die Anwendung verfügbar ist. Die Funktion akzeptiert zwei optionale Parameter: ob eine Schließen-Schaltfläche im Werbevideo angezeigt werden soll, und ob eine optionale Zeichenfolge zur Benutzerkennung angezeigt werden soll (diese kann mit den serverseitigen WebHooks von Vungle verwendet werden, um ein HTTP GET auszulösen, wenn ein Nutzer die Wiedergabe abgeschlossen hat):

if (Vungle.vungle.isAdAvailable())
{
    var config:VungleAdConfig = new VungleAdConfig();
    config.incentivized = true;
    Vungle.vungle.playAd(config);
}

Um den Spieler für die vollständige Wiedergabe mit Anreiz zu belohnen, ist die Implementierung des Event Listeners AD_VIEWED möglich (unten beschrieben).

Add Event Listeners

The Vungle Extension dispatches five events: VungleEvent.AD_PLAYABLE, VungleEvent.AD_STARTED, VungleEvent.AD_FINISHED, VungleEvent.AD_VIEWED and VungleEvent.AD_LOG.

  1. AD_PLAYABLE wird versendet, wenn das Werbevideo wiedergegeben werden kann 
    Vungle.vungle.addEventListener(VungleEvent.AD_PLAYABLE, onAdPlayable);
    
    function onAdPlayable(e:VungleEvent):void
    {
        trace("ad playable");
    }
    
  2. Die Ereignisse AD_STARTED und AD_FINISHED werden versendet, wenn ein Werbevideo angezeigt wird bzw. abgelehnt wird:

    Vungle.vungle.addEventListener(VungleEvent.AD_STARTED, onAdStarted); 
    Vungle.vungle.addEventListener(VungleEvent.AD_FINISHED, onAdFinished); 
    
    function onAdStarted(e:VungleEvent):void 
    { 
      trace("ad displayed"); 
    } 
    
    function onAdFinished(e:VungleEvent):void
    { 
      trace("ad dismissed: " + e.wasCallToActionClicked);
    }
  3. Das Ereignis AD_VIEWED wird ausgelöst, wenn der Nutzer nicht mehr im Vungle-Video ist und einen Teil des Videos gesehen hat. Die Eigenschaft ,angesehen‘ entspricht der Zeit in Sekunden, die der Nutzer das Video angesehen hat. Die Eigenschaft ,Länge‘ entspricht der Gesamtdauer des Videos.

    (Dieses Ereignis wird möglicherweise nicht immer abgerufen, wie z. B. wenn die Werbung eine Pre-Roll-HTML-Anlage enthält und der Nutzer die Werbung schließt, bevor er das Video angesehen hat.)

    Damit Werbevideos mit Anreiz als gesehen gelten, müssen mehr als 80 % des Videos gesehen worden sein:

    Vungle.vungle.addEventListener(VungleEvent.AD_VIEWED, onAdViewed); 
    
    function onAdStarted(e:VungleEvent):void 
    { 
      trace("watched"+e.watched+" of "+e.length+" second video."); 
      var percentComplete:Number=e.watched/e.length; 
      if(percentComplete>0.80) 
      { 
        trace("counts a completed view- present reward."); 
      } 
    }
  4. AD_LOG wird versendet, wenn ein Protokolleintrag vom Vungle-SDK gesendet wurde. Es kann zur Fehlerbeseitigung verwendet werden. Die Protokollierung wird nur im Vungle-SDK für iOS implementiert, damit dieses Ereignis plattformspezifisch ist.

    
    Vungle.vungle.setLoggingEnabled(true);
    Vungle.vungle.addEventListener(VungleEvent.AD_LOG, onAdLog);
    
    private function onAdLog(e:VungleEvent):void
    {
        log("ad log: " + e.message);
    }
    

Toggle Auto-rotation

Die setAutoRotationEnabled()-Methode kann verwendet werden, um festzustellen, ob Videos automatisch in die Ausrichtung des Gerätes gedreht werden:

Vungle.vungle.setAutoRotation(true);

Weitere Optionen

Wie bereits vorher festgestellt wurde, kann ein Objekt mit Konfigurationsoptionen hinzugefügt werden, wenn die playAd()-Methode abgerufen wird. Dies sind die verfügbaren Eigenschaften in VungleAdConfig:

orientation

Mit dieser Eigenschaft kann die Ausrichtung des Werbevideos spezifiziert werden. Es gibt verschiedene Markierungsgruppen für Android und für iOS. Weitere Informationen finden Sie in der VungleOrientation-Klasse. Die Markierungen können mit einem bitweisen OR-Operator versehen werden:

config.orientation = VungleOrientation.ANDROID_AUTOROTATE | VungleOrientation.IOS_PORTRAIT;

soundEnabled

Diese Eigenschaften können verwendet werden, um festzustellen, ob Werbevideos mit oder ohne Ton wiedergegeben werden.

backButtonImmediatelyEnabled

Diese Option ist Android-spezifisch. Bei true kann der Benutzer eine Werbung unmittelbar mit der Schaltfläche „Zurück” verlassen. Bei false kann der Benutzer die Werbung erst dann mit der Schaltfläche "Zurück" verlassen, wenn die Schaltfläche „Schließen" auf dem Bildschirm angezeigt wird.

immersiveMode

Diese Option ist Android-spezifisch. Damit wird der Immersive Mode auf KitKat+-Geräten aktiviert oder deaktiviert werden.

incentivized

Stellt den Anreiz-Modus ein. Bei true wird dem Nutzer ein Bestätigungsdialog angezeigt, wenn er versucht, die Werbung zu überspringen.

incentivizedUserId

Die einmalige Nutzer-ID wird Ihrer Anwendung übergeben, um zu überprüfen, dass dieser Nutzer für das Sehen des Werbevideos mit Anreiz belohnt wird.

incentivizedCancelDialogTitle, incentivizedCancelDialogBodyText, incentivizedCancelDialogCloseButtonText, incentivizedCancelDialogKeepWatchingButtonText

Diese Optionen ermöglichen eine individuelle Anpassung des Bestätigungsdialogs, der beim Überspringen des Werbevideos mit Anreiz angezeigt wird.

extra1 … extra8

Dies kann verwendet werden, um Metriken wie Altersgruppe, Geschlecht und andere nachzuverfolgen.

placement

Optionaler Name für die Werbeplatzierung und für die erweiterte Berichterstellung auf dem Dashboard.

largeButtons

Diese Option ist iOS-spezifisch. Bei true werden die über dem Video angezeigten Schaltflächen größer sein.

 

Globale Vorgaben

Sie können globale Konfigurationsobjekte verwenden, um die Standard-Werte für diese Optionen einzustellen:


// Beliebige Konfigurationsoptionen festlegen.
VungleAdConfig.globalConfig.orientation = VungleOrientation.ANDROID_MATCH_VIDEO;
VungleAdConfig.globalConfig.soundEnabled = false;

Dann wird ein neues VungleAdConfig-Objekt mit diesen standardmäßig eingestellten Werten erstellt. playAd() ohne Optionen werden ebenso die globalen Einstellungen.

Veraltete Methoden

Seit v2.4.0 wurden die folgenden Methoden abgelehnt:


Vungle.vungle.displayAd(showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.displayIncentivizedAd(name:String, showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.setSoundEnabled(enabled:Boolean):void;
Vungle.vungle.setBackButtonEnabled(backEnabled:Boolean):void;
Vungle.vungle.setIncentivizedBackButtonEnabled(backEnabled:Boolean):void;

Diese Methoden wurden für Abwärtskompatibilität gehalten. Es wird empfohlen, diese nicht für neue Anwendungen zu verwenden oder mit dem Aufruf der playAd()-Methode zu vermischen.

Fehlerbehebung und FAQ

„Wie verwende ich die VungleBeispiel-Dokumentenklasse in Flash CS6?”

  1. Erstellen Sie zunächst die Anwendung und fügen Sie die Erweiterung hinzu, indem Sie den Anweisungen dieser Leitfadens in Abschnitt 1 bis 3 folgen.

  2. Kopieren Sie VungleExample.as und fügen Sie es in denselben Order wie Ihr .fla ein. Fügen Sie die kopierten Inhalte nicht in die Zeitlinie ein. Dies wird nicht funktionieren.

  3. Ändern Sie die App-IDs auf Zeile 51, damit Sie Ihren Vungle App-IDs entsprechen.

  4. Geben Sie in den Flash-Eigenschaften unter ,Dokumentenklasse‘ ,VungleExample‘ (ohne Anführungszeichen) ein und drücken Sie OK.

  5. Erstellen und installieren Sie die Anwendung.

„Wie installiere ich eine neuere Version von AIR SDK (4.0 oder höher) in Flash Professional CS6?”

Unter diesem Link finden Sie the latest AIR SDK. Wenn Sie AIR 4.0 oder höher bereits installiert haben, kann dieser Schritt übersprungen werden. Ansonsten befolgen Sie die unten beschriebenen Anweisungen:

  1. Entpacken Sie das Paket von AIR 4.0 oder höher in ein Verzeichnis auf Ihrer Festplatte.

  2. Starten Sie Flash Professional CS6.

  3. Wähle Sie Hilfe > AIR SDK verwalten...

  4. Drücken Sie die Plus-Taste (+) und navigieren Sie zu dem Verzeichnis, in dem AIR SDK entpackt wurde.

  5. Drücken Sie OK

  6. Datei auswählen > Veröffentlichungseinstellungen

  7. Wählen Sie das aktuellste AIR SDK für iOS aus dem ,Ziel‘-Dropdownmenü.

„Wie installiere ich eine neuere Version von AIR SDK (4.0 oder höher) in Flash Builder?”

Unter diesem Link finden Sie the latest AIR SDK. Wenn Sie AIR 4.0 oder höher bereits installiert haben, kann dieser Schritt übersprungen werden. Sie können auch die neusten Anweisungen von Adobe zur Aktualisierung von Flash Builder AIR SDKs verwenden.

 

Haben Sie Fragen? Anfrage einreichen

Kommentare