Erste Schritte mit Vungle – iOS SDK v. 6 (Swift)

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 dann diese Zustimmung bzw. Ablehnung für nachfolgende Werbung.

Bevor Sie anfangen

  • Vungle iOS SDK v. 6 unterstützt iOS 8+.
  • 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. Wenn Sie noch kein Konto besitzen, erstellen Sie zunächst eins.
  • Unser neuestes iOS SDK (seit V. 4.0.8) wurde speziell für die neueste Version von Xcode 8.0 herausgegeben. Sie sollten daher Xcode 8.0 oder eine neuere Version nutzen, um eine reibungslose Integration zu gewährleisten.
  • Der Quellcode, auf den hier Bezug genommen wird, ist über unsere öffentliche GitHub-Repository verfügbar.

 

Schritt 1. Fügen Sie das Vungle Framework Ihrem Xcode-Projekt hinzu

Fügen Sie VungleSDK.framework Ihrem Projekt hinzu

Es gibt zwei Wege, Vungle 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 die Podfile Ihres Projekts einfügen.

 pod "VungleSDK-iOS", "6.x"

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

Manuelle Integration

Laden Sie das Vungle SDK v6.x herunter. Wenn Sie von einer früheren Version des Vungle SDK updaten, entfernen Sie zunächst das Verzeichnis VungleSDK.framework vollständig. Suchen Sie dann die extrahierten Dateien und ziehen Sie 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, wenn sie noch nicht enthalten sind:

  • AdSupport.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • CFNetwork.framework
  • CoreGraphics.framework
  • CoreMedia.framework
  • Foundation.framework
  • libz.dylib or libz.tbd
  • libsqlite3.dylib or libsqlite3.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    Hinweis: Setzen Sie den WebKit.framework Status auf „Optional“, wenn iOS 7 Ihr Installationziel ist.

Stellen Sie sicher, 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 → Andere verlinkte Flags auf. Fügen Sie ObjC den Anderen 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 sichergestellt 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 hinzu und setzen Sie ihn auf Nein.

Schritt 3. Fügen Sie Programmcode ein

Erstellen Sie eine Bridging Header-Datei

  1. Erstellen Sie eine neue Objective-C-Datei in Ihrem Projekt (Datei Neu Datei [Objective-C Datei]).
  2. Sie werden in Xcode gefragt, ob Sie eine Bridging Header-Datei zwischen Objective-C und Swift erstellen möchten. Bestätigen Sie diese Anfrage.
  3. Löschen Sie die neue Objective-C-Datei (${YOURPROJ}-Bridging-Header.m), aber behalten Sie die Bridging Header-Datei ${YOURPROJ}-Bridging-Header.h bei.
  4. Importieren Sie in die Bridging Header-Datei das Vungle SDK, indem Sie Folgendes hinzufügen:
    #import <VungleSDK/VungleSDK.h> 

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 placements:(nonnull NSArray *)placements error:(NSError **)error;

Beispielcode:

let appID = "Your_AppID_Here";
var placementIDsArray:Array<String> = ["<Your_PlacementID_1>", "<Your_PlacementID_2>", "<Your_PlacementID_3>"];

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.start(withAppId: appID, placements: placementIDsArray)
}
catch let error as NSError {
print("Error while starting VungleSDK : \(error.domain)")
return;
}

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

- (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 betrachtete Platzierung zum automatischen Cachen auszuwählen.

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

Laden einer Werbung für eine Platzierung

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

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.loadPlacement(withID: <Your_PlacementID>)
}
catch let error as NSError {
print("Unable to load placement with reference ID :\(<Your_PlacementID>), Error: \(error)")

return
}

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 für eine Platzierung gecacht hat, wird die folgende Callback-Methode aufgerufen:

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

Beispielcode:

func vungleAdPlayabilityUpdate(_ isAdPlayable: Bool, placementID: String?) {
if (placementID == <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 wird 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 Sie sichergestellt haben, dass eine Werbung zur Platzierung bereit steht, können Sie sie mit folgender Methode abspielen:

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

Beispielcode:

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.playAd(self, options: nil, placementID: kVungleTestPlacementID01)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

Delegierte Callbacks:

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

Sie können Ihren Delegierten wie folgt abtrennen:

var sdk:VungleSDK = VungleSDK.shared()
// Attach
sdk.delegate = <yourDelegateInstance> as VungleSDKDelegate
// Detach
sdk.delegate = nil

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

Die folgende Methode wird aufgerufen, wenn das SDK gleich ein Werbevideo wiedergeben wird. Dies ist eine gute Gelegenheit, um Spiele, Audioeffekte, Animationen usw. zu pausieren.

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

Die folgende Methode wird aufgerufen, wenn das SDK gleich ein Werbevideo schließen wird. Dies ist eine gute Gelegenheit, um Ihren Nutzer zu belohnen und um Spiele, Audioeffekte, Animationen usw. wiederaufzunehmen.

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

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

- func vungleDidCloseAd(with info: VungleViewInfo, placementID: String);

Die Klasse VungleViewInfo beinhaltet die folgenden Eigenschaften, die Ihnen zur Ergebnisprüfung nach dem Abspielen einer Werbung zur Verfügung stehen:

@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:(NSString *)placementID;

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 der Werbedarstellung beim Abspielen.

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

Optionstasten

Standardwert / Typ

Beschreibung

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

Eine NSString als eine 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 über das 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 möglicherweise keine Belohnung."

NSString

Zeichenfolge, 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.

Beispielcode:

let options: NSDictionary = NSDictionary(dictionary: [VunglePlayAdOptionKeyUser: "test_user_id",
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!"])
do {
try self.sdk.playAd(self, options: (options as! [AnyHashable : Any]), placementID: PlacementID)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

Stummstellen-Option

Die Instanz des Vungle SDK bietet die Möglichkeit, Werbung ohne Ton abzuspielen. Sie können vor der Ausgabe von playAd() die Option "muted" (stummgestellt) auf "true" stellen.

Beispielcode:

var sdk:VungleSDK = VungleSDK.shared()
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.

Debuggen

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

- (NSDictionary *)debugInfo;

Wenn Sie möchten, dass das SDK Logs ausgibt, verwenden Sie die 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 Protollierung aktiviert ist). Verwenden Sie folgenden Programmcode, um Ihren Logger anzufügen:

- (void)attachLogger:(id<VungleSDKLogger>)logger;

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:

- (void)detachLogger:(id<VungleSDKLogger>)logger;

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 verwendet:

//This function returns the current consent status recorded in SDK. If status is not known return 0. sdk = VungleSDK.shared() sdk?.getCurrentConsentStatus() //This function sets the current consent status recorded in the SDK sdk = VungleSDK.shared() sdk?.update(status: VungleConsentStatus) 

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

  • Akzeptiert (VungleConsentStatus.accepted)
  • Abgelehnt (VungleConsentStatus.denied)
Haben Sie Fragen? Anfrage einreichen

Kommentare