Erste Schritte mit Vungle – iOS SDK v. 5

Inhalt

Bevor Sie anfangen

  • Das Vungle iOS SDK v. 5 unterstützt iOS 8+.
  • Das Vungle iOS SDK v. 5 wurde mit iOS 11 beta/GM Seed getestet.
  • Das Vungle iOS SDK v. 5 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 iOS SDK unterstützt Xcode 9.0 und höher.

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", "5.4.0"

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 Vungle SDK v. 5 herunter. Wenn Sie von einer früheren 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 unter 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
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    Hinweis: Vungle v.5 unterstützt iOS 7 nicht. Wenn iOS 7 Ihr Installationsziel ist, benutzen Sie Vungle iOS SDK V. 4.1 oder eine frühere Version.

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

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. Sie benötigen zur Initialisierung des SDK die App-ID und alle Platzierungsreferenz-IDs, die Sie in Ihrer App verwenden möchten (sowohl aktive als auch inaktive). Diese IDs finden Sie im Vungle Dashboard (sehen Sie im Abschnitt Einstellung von Placements in Ihrem Vungle Dashboard nach).

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

Beispielcode:

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here"; NSArray* placementIDsArray = @[@"<Your_PlacementID_1>", @"<Your_PlacementID_2>", @"<Your_PlacementID_3>"]; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk startWithAppId:appID placements:placementIDsArray error:&error];

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, cacht 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 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" dieses 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.

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

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

Beispielcode:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID { 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 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:

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

Wir unterstützen Flex Feed-Werbung seit Vungle SDK v.5.3. Dies ist das erste Werbeformat, das keinen Vollbildschirm erfordert. Stattdessen bestimmt der Herausgeber die exakten Abmessungen und die Platzierung des Werbungs-Containers in 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.

Flex Feed-Anzeige anzeigen

Die Anzeige von Flex Feed-Werbung unterscheidet sich 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 wird sich an jede Größe des Containers anpassen. Beachten Sie aber, dass eine sehr niedrige Auflösung die Sichtbarkeit der Anzeige verringert. Danach müssen Sie die Funktion addAdViewToView aufrufen, um den Container einer Flex Feed-Anzeige 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); } 

Flex Feed-Anzeige schließen

Aufgrund der Eigenschaften von Flex Feed-Werbung können Nutzer 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 Delegierten, in dem Sie über SDK-Events benachrichtigt werden.

Sie können Ihren Delegierten wie folgt abtrennen:

// Attach [[VungleSDK sharedSDK] setDelegate:yourDelegateInstance]; // Detach [[VungleSDK sharedSDK] setDelegate: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; 

VungleViewInfo includes the following properties for you to check a result of ad play:

@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 NSNumber 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.

VunglePlayAdOptionKeyFlexViewAutoDismissSeconds

Int

Mit dieser Option können Sie Flex View-Werbung automatisch nach einer bestimmten Anzahl von Sekunden ablehnen.
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 Spielesitzung 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, Werbung ohne Ton abzuspielen. Sie können vor der Ausgabe von playAd() die Option "muted" (stummgestellt) auf "true" stellen.

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.

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:

[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