Erste Schritte mit Vungle – iOS SDK v. 6

Inhalt

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

  • Vungle iOS SDK V. 6 unterstützt iOS 8+.
  • Das Vungle iOS SDK v. 6 wurde mit iOS 11 beta/GM Seed getestet.
  • Vungle iOS SDK V. 6 unterstützt sowohl 32-Bit als auch 64-Bit-Apps.
  • Für die Integration benötigen Sie ein Vungle-Konto. Falls Sie noch kein Konto besitzen, erstellen Sie zunächst eines.
  • Unser iOS SDK unterstützt Xcode 9.0 und höher.

Schritt 1. Fügen Sie das Vungle Framework in Ihr Xcode-Projekt ein

Fügen Sie VungleSDK.framework Ihrem Projekt hinzu

Es gibt zwei Wege, Vungle zu Ihrem Xcode-Projekt hinzuzufügen: unter Verwendung von Cocoapods oder durch manuelle Integration.

Cocoapods

Das Vungle SDK ist über Cocoapods verfügbar. Fügen Sie Vungle Ihrem Projekt hinzu, indem Sie die folgende Zeile in das Podfile Ihres Projekts eintragen.

 pod "VungleSDK-iOS", "6.2.0"

Anschließend sollte eine schnelle Pod-Installation Ihr Projekt mit der neuesten Version unseres iOS SDK aktualisieren. Zu diesem Zeitpunkt können Sie mit "Schritt 2. Die iOS-Statusleiste entfernen" fortfahren.

Manuelle Integration

Laden Sie Vungle SDK v. 6 herunter. Wenn Sie von einer vorherigen Version des Vungle SDK aktualisieren, entfernen Sie zuerst das Verzeichnis VungleSDK.framework vollständig, bevor Sie das neue SDK hinzufügen.

Suchen Sie die extrahierten Dateien und ziehen Sie dann das VungleSDK.framework-Verzeichnis nach Xcode unterhalb Frameworks. Stellen Sie sicher, dass der VungleSDK.framework-Ordner als Gruppe (gelber Ordner) und nicht als Referenz (blauer Ordner) hinzugefügt wird.

Weitere erforderliche Frameworks hinzufügen

Für das Vungle SDK müssen einige weitere native Frameworks mit Ihrem Projekt verlinkt werden. Klicken Sie dazu auf Ihr Projekt im Projektnavigator und wählen Sie Allgemein → Verlinkte Frameworks und Bibliotheken.

Viele dieser Frameworks sind bereits als Standardeinstellung der meisten Xcode-Projekte enthalten. Stellen Sie jedoch sicher, dass sie die folgenden Frameworks hinzufügen, falls sie noch nicht enthalten sind:

  • AdSupport.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • CFNetwork.framework
  • CoreGraphics.framework
  • CoreMedia.framework
  • libz.dylib or libz.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework


Hinweis: Vungle v.6 unterstützt iOS 7 nicht. Wenn iOS 7 Ihr Installationsziel ist, benutzen Sie Vungle iOS SDK V. 4.1 oder eine frühere Version und fügen Sie folgende Frameworks hinzu:

  • UIKit.framework
  • WebKit.framework
  • Foundation.framework

Sorgen Sie dafür, dass das VungleSDK-Framework unter Verknüpfte Frameworks und Bibliotheken erscheint.

Fügen Sie das Linker Flag "-ObjC" hinzu

Klicken Sie im Projektnavigator auf Ihr Projekt und rufen Sie Build Settings → Verlinkung → Weitere Linker Flags auf. Fügen Sie ObjC Weitere Linker Flags hinzu.

Schritt 2. Entfernen Sie die iOS-Statusleiste

Dieser Schritt ist nicht notwendig, wird aber empfohlen, da durch das Entfernen der iOS-Statusleiste gewährleistet wird, dass die Werbungsinteraktion und -Präsentation von Vungle reibungslos funktionieren. Um die Statusleiste zu entfernen, öffnen Sie Ihre Info.plist und fügen Sie den Schlüssel Controller-basierte Statusleistenanzeige einblenden ein und setzen Sie ihn auf Nein.

Schritt 3. Fügen Sie den entsprechenden Programmcode ein

Initialisieren Sie das SDK

Initialisieren Sie das SDK, sobald Ihre App startet. Bei Verwendung einer automatisch gecachten Platzierung gewähren Sie dadurch dem SDK ausreichend Zeit zum Cachen dieser Werbung. Sie benötigen die App-ID, um das SDK zu initialisieren. Sie finden Sie im Vungle Dashboard.

- (BOOL)startWithAppId:(nonnull NSString *)appID error:(NSError **)error;

Beispielcode:

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here"; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk startWithAppId:appID error:&error];

Sobald das SDK erfolgreich initialisiert wurde, wird die folgende Callback-Methode gerufen:

- (void)vungleSDKDidInitialize;

Sehen Sie im Abschnitt "Delegieren von Callbacks" dieses Artikels nach.

Sie können den Status der SDK-Initialisierung auch mit der folgenden Eigenschaft prüfen:

@property (atomic, readonly, getter=isInitialized) BOOL initialized;

Nachdem das SDK initialisiert wurde und Sie eine Platzierung im Vungle Dashboard als automatisch gecacht ausgewählt haben, cacht es automatisch eine Werbung für diese Platzierung. Wir empfehlen bei Nutzung dieser Funktion die am häufigsten angesehene Platzierung als Ihre automatisch gecachte Auswahl.

Sobald eine Werbung erfolgreich gecacht wurde, wird die Callback-Methode vungleAdPlayabilityUpdate mit der Referenz-ID der Platzierung, die zu Ihrer automatisch gecachten Platzierung passt, aufgerufen. (Sehen Sie im Abschnitt "Werbungsverfügbarkeit für eine Platzierung prüfen" in diesem Artikel nach.)

Laden einer Werbung zur Platzierung

Für alle weiteren Platzierungen außer der automatisch gecachten Platzierung, rufen Sie die loadPlacementWithID Methode, um eine Werbung zu laden.

- (BOOL)loadPlacementWithID:(NSString *)placementID error:(NSError **)error;

Beispielcode:

NSError* error;
VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk loadPlacementWithID:"<Your_PlacementID>" error:&error];

Sehen Sie im Abschnitt "Werbungsverfügbarkeit für eine Platzierung prüfen" in diesem Artikel nach.

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

Sobald das SDK erfolgreich eine Werbung zur Platzierung gecacht hat, wird die folgende Callback-Methode aufgerufen:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID error:(nullable NSError *)error; 

Beispielcode:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID error:(nullable NSError *)error; 

Sample code: 

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID error:(nullable NSError *)error {
    if([placementID isEqualToString:@"<Your_PlacementID>"]) {
        self.playButtonPlacement1.enabled = isAdPlayable;
    }
}

Hinweis: Für die automatisch gecachte Platzierung wird die Callback-Methode nur aufgerufen, wenn eine Werbung verfügbar wird. Das SDK fordert weiterhin eine Werbung für die automatisch gecachte Platzierung an. Bei allen anderen Platzierungen wirf die Callback-Methode im Fall von "Load Failed" aufgerufen (isAdPlayable gibt in diesem Fall "NO" zurück).

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

- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID;

Abspielen einer Werbung

Nachdem nun gewährleistet ist, dass eine Werbung für die Platzierung bereit ist, können Sie sie mittels folgender Methode abspielen:

- (BOOL)playAd:(UIViewController *)controller options:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;

Beispielcode:

VungleSDK* sdk = [VungleSDK sharedSDK]; NSError *error; [self.sdk playAd:self options:nil placementID:@"<Your_PlacementID_1>" error:&error]; if (error) { NSLog(@"Error encountered playing ad: %@", error); }

Flex Feed-Werbung

Wir unterstützen Flex Feed-Werbung seit Vungle SDK v.5.3. Dies ist das erste Werbeformat, das keine Vollbild-Anzeige erfordert. Stattdessen bestimmt der Herausgeber die exakten Abmessungen und die Positionierung des Werbungs-Containers innerhalb der App.

Flex Feed-Anzeige laden

Eine Flex Feed-Anzeige wir auf die gleiche Weise wie eine Vollbildanzeige geladen; allerdings muss die Platzierung so eingestellt werden, dass sie Flex Feed unterstützt. Wenden Sie sich an Ihren Vungle Account-Manager, um Flex Feed für eine Platzierung zu aktivieren.

Eine Flex Feed-Werbung anzeigen

Das Anzeigen von Flex Feed-Werbung unterscheidet sich von dem von Vollbildanzeigen. Bei Flex Feed-Werbung müssen Sie zuerst einen Container für die Anzeige erstellen. Dieser Container ist ein UIView. Sie können diesen UIView an beliebiger Stelle auf dem Display platzieren. Die Anzeige lässt sich auf jede Größe des Containers skalieren. Beachten Sie aber, dass eine sehr niedrige Auflösung die Sichtbarkeit der Anzeige verringert. Anschließend müssen Sie die Funktion addAdViewToView aufrufen, um den Container einer Flex Feed-Werbung zuzuordnen.

Funktionsübersicht:

/** * Pass in an UIView which acts as a container for the ad experience. This view container may be placed in random positions. * @param publisherView container view in which an ad will be displayed * @param options A reference to an instance of NSDictionary with customized ad playback options * @param placementID The placement defined on the Vungle dashboard * @param error An optional double reference to an NSError. In case this method returns `NO` it will be non-nil * @return YES/NO in case of success/error while presenting an AdUnit */ - (BOOL)addAdViewToView:(UIView *)publisherView withOptions:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error; 

Beispielcode:

NSError *error; NSDictionary *options = @{}; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk addAdViewToView:_FlexFeedViewArea withOptions:options placementID: error:&error]; if (error) { NSLog(@"Error encountered while playing an ad: %@", error); } 

Eine Flex Feed-Anzeige schließen

Aufgrund der Eigenschaften von Flex Feed-Werbung können Benutzer das Video anhalten, ohne dabei die Anzeige zu schließen. Sie müssen daher dem SDK mitteilen, die Werbung zu entfernen, sobald sie sich nicht mehr im Bildschirmbereich befindet. Rufen Sie dazu die finishedDisplayingAd-Funktion auf. Beachten Sie, dass diese Funktion keine Platzierung aufnimmt; sie dient lediglich dazu, jede native Werbung, die gerade abgespielt wird, zu schließen.

Funktionsübersicht:

/** * This method must be called when the publisher is confident that they are finished displaying the ad unit. * This signals to the SDK that a new ad may be fetched or a different ad may be displayed. This will * be called in conjunction with `addViewToView:containedInViewController:withOptions:placementID:error:` */ - (void)finishedDisplayingAd; 

Beispielcode:

//Ad is no longer on screen VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk finishedDisplayingAd]; 

Delegierte Callbacks:

Sie können vom SDK Callbacks durch VungleSDKDelegate erhalten. Es gibt vier Callback-Methoden im Delegate, in dem Sie über SDK-Events benachrichtigt werden.

Sie können den Delegate wie folgt anfügen bzw. abtrennen:

// Attach [[VungleSDK sharedSDK] setDelegate:yourDelegateInstance]; // Detach [[VungleSDK sharedSDK] setDelegate:nil]; 

Hinweis: Denken Sie daran, zur Vermeidung von Speicherlecks den registrierten Delegate zu bereinigen, wenn er nicht mehr benötigt wird.

Die folgende Methode wird aufgerufen, wenn das SDK gerade dabei ist, ein Werbevideo zu schließen. An diese Stelle bietet es sich an, Spiele, Audioeffekte, Animationen etc. pausieren zu lassen.

- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID; 

Die folgende Methode wird aufgerufen, wenn das SDK gerade dabei ist, ein Werbevideo zu schließen. Hier bietet es sich an, Ihren Nutzer zu belohnen und die Wiedergabe von Spielen, Audioeffekten, Animationen etc. wiederaufzunehmen.

- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID; 

Die folgende Methode wird aufgerufen, wenn das SDK eine Werbeanzeige geschlossen hat:

- (void)vungleDidCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;

VungleViewInfo beinhaltet die folgenden Eigenschaften, mit denen Sie das Ergebnis einer abgespielten Werbeanzeige überprüfen können:

@interface VungleViewInfo : NSObject //Represents a BOOL whether or not the video can be considered a completed view. @property (nonatomic, readonly) NSNumber *completedView; //The time in seconds that the user watched the video. @property (nonatomic, readonly) NSNumber *playTime; //Represents a BOOL whether or not the user clicked the download button. @property (nonatomic, readonly) NSNumber *didDownload; @end 

Die folgende Methode wird aufgerufen, wenn das SDK den Werbungsverfügbarkeitsstatus geändert hat. Der isAdPlayable Boolean gibt die neue Wiedergabefähigkeit einer bestimmten placementID an.

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID error:(nullable NSError *)error;

Sehen Sie im Abschnitt "Werbungsverfügbarkeit für eine Platzierung prüfen" in diesem Artikel nach.

Die folgende Methode wird aufgerufen, wenn das SDK erfolgreich initialisiert wurde:

- (void)vungleSDKDidInitialize;

Anpassungsoptionen

Verwenden Sie diese Optionen zur Anpassung des Werbungserlebnisses beim Abspielen.

Hinweis: Belohnte Anzeigen (rewarded ads) werden im Englischen mitunter auch 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”.

Optionstasten

Standardwert / Typ

Beschreibung

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

Eine NSNumber als Bit-Maske mit Ausrichtungen

Legt die Ausrichtung der Werbung fest. Wir empfehlen, automatisches Drehen (autorotate) für Werbungen zuzulassen, selbst wenn Ihre App nur im Hochformat verwendet wird. So hat der Nutzer die Möglichkeit, Videos in voller Größe anzusehen. Sie erreichen dies, indem Sie die Ausrichtung auf Ebene des Ansichtscontrollers festlegen (und nicht auf Projektebene).

VunglePlayAdOptionKeyUser

nil

NSString

Legt Ihre Nutzer-ID fest. Der Wert wird an den Vungle-Server weitergegeben und dann mittels server-zu-server Callback-System an Ihren Server gesendet, wenn eine Platzierung als „Belohnt" eingestellt wird.

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertBodyText

„Möchten Sie diese Werbung wirklich überspringen? In diesem Fall erhalten Sie unter Umständen keine Belohnung.“

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

„Schließen“

NSString

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.

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

„Fortfahren“

NSString

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.

VunglePlayAdOptionKeyFlexViewAutoDismissSeconds

Int

Mit dieser Option können Sie Flex View-Werbung automatisch nach einer bestimmten Anzahl von Sekunden ausblenden.
Diese Funktion ist nur für Flex View-Werbung verfügbar.

VunglePlayAdOptionKeyOrdinal

Int

Wenn Sie Ordinaldaten-Berichte von Vungle bekommen, verwenden Sie dieses Feld zur Übergabe der Mediations-Ordinalen. Dies ist eine Ganzzahl, die die Reihenfolge angibt, in der diese Werbeanzeige in der Spielsitzung gezeigt wurde (wenn beispielsweise in einer Sitzung bereits zwei Werbungen gezeigt wurden und dann jene von Vungle als dritte folgt, ist der Wert „3“. Mehr zu Ordinaldaten erfahren Sie hier.


NSDictionary *options = @{VunglePlayAdOptionKeyOrientations: @(UIInterfaceOrientationMaskLandscape), VunglePlayAdOptionKeyUser: @"userGameID", VunglePlayAdOptionKeyIncentivizedAlertBodyText : @"If the video isn't completed you won't get your reward! Are you sure you want to close early?", VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText : @"Close", VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText : @"Keep Watching", VunglePlayAdOptionKeyIncentivizedAlertTitleText : @"Careful!"}; // Pass in dict of options, play ad NSError *error; [self.sdk playAd:self options:options placementID: error:&error]; if (error) { NSLog(@"Error encountered playing ad: %@", error); }

Stummstellen-Option

Die Instanz des Vungle SDK bietet die Möglichkeit zum lautlosen Abspielen von Werbungen. Sie können vor der Ausgabe von playAd() die Option "muted" (stumm gestellt) auf "true" setzen.

Beispielcode:

VungleSDK* sdk = [VungleSDK sharedSDK]; self.sdk.muted = true;

Hinweis: Diese Option trifft nur auf den Standard-Werbungstyp zu. Die Option "muted" kann im Dashboard für dynamische Vorlagen-Werbungen eingestellt werden.

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:

// This function sets the consent status that will be recorded in Vungle SDK. Accepted values: 'VungleConsentAccepted' or 'VungleConsentDenied'.
// To set the user's consent status to opted in:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentAccepted];

// To set the user's consent status to opted out:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentDenied];

// To find out what the user's current consent status is:
// (Check against enum values: 'VungleConsentAccepted' or 'VungleConsentDenied'.) [[VungleSDK sharedSDK] getCurrentConsentStatus];

VungleConsentStatus ist eine Aufzählung mit zwei Zuständen:

  • VungleConsentAccepted
  • VungleConsentDenied

Das SDK besitzt zudem einen Ausgangszustand „unbekannt“. Der Benutzer muss daher aktiv die Datenerfassung auswählen oder abwählen. Beachten Sie, dass diese Abfrage nur bei IP-Adressen aus Europa erfolgt.

Debuggen

Falls Sie SDK-Informationen benötigen, können Sie diese mit Hilfe der folgenden Eigenschaft beziehen:

- (NSDictionary *)debugInfo;

Wenn das SDK Log-Dateien ausgeben soll, verwenden Sie folgende Methode:

- (void)setLoggingEnabled:(BOOL)enable;

VungleSDKLogger -Protokoll

@protocol VungleSDKLogger - (void)vungleSDKLog:(NSString*)message; @end

Der VungleSDK-Singleton sendet Logging-Events an alle angefügten Klassen nach dem VungleSDKLogger-Protokoll. Das Log-Event enthält den NSString-Wert, der außerdem auf der Konsole ausgegeben wird (sofern die Log-Funktion aktiviert ist). Verwenden Sie folgenden Code, um Ihren Logger anzufügen:

[sdk attachLogger:yourLoggerInstance];

Wie bereits erwähnt, ist es wichtig, angefügte Logger aus dem Vungle SDK zu löschen. Gehen Sie folgendermaßen vor, um Logger zu trennen:

[sdk detachLogger:yourLoggerInstance];

assetLoader-Protokoll

@protocol VungleAssetLoader /** * Sollte ein gültiges NSData-Element mit den (Roh-)Daten eines Abbilds für den angegebenen Pfad oder "nil" zurückgeben. */ - (NSData*)vungleLoadAsset:(NSString*)path; /** * Sollte ein gültiges UIImage-Element für den angegebenen Pfad oder "nil" zurückgeben. */ - (UIImage*)vungleLoadImage:(NSString*)path; @end
Haben Sie Fragen? Anfrage einreichen

Kommentare