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 haben, erstellen Sie eines, bevor Sie fortfahren.
  • Unser iOS SDK unterstützt Xcode 8.0 und 9.0. Sie sollten daher Xcode 8.0 oder eine neuere Version nutzen, um eine reibungslose Integration zu gewährleisten.

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

Fügen Sie VungleSDK.framework zu 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 zu Ihrem Projekt hinzu, indem Sie die folgende Zeile zum Podfile Ihres Projekts hinzufügen.

 pod "VungleSDK-iOS", "5.3.0"

Danach sollte eine schnelle Pod-Installation-Ausführung Ihr Projekt mit der neuesten Version unseres iOS SDK aktualisieren. Zu diesem Zeitpunkt können Sie zu "Schritt 2. Die iOS-Statusleiste entfernen" fortfahren.

Manuelle Integration

Laden Sie Vungle SDK v. 5 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 unter Frameworks. Stellen Sie sicher, dass der VungleSDK.framework-Ordner als Gruppe (gelber Ordner) und nicht als Referenz (blauer Ordner) hinzugefügt wird.

Andere 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: Wählen Sie den WebKit.framework Status „Optional”, wenn Ihr Zielsystem iOS 7 ist.

Stellen Sie sicher, dass das VungleSDK-Framework unter Verknüpfte Frameworks und Bibliotheken erscheint.

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

Klicken Sie im Projektnavigator auf Ihr Projekt und rufen Sie Baueinstellungen → 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 die Entfernung 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 Code hinzu

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 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 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 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, gerufen. (Sehen Sie im Abschnitt "Werbungsverfügbarkeit für eine Platzierung prüfen" dieses article.) 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 gerufen, wenn eine Werbung verfügbar wird. Das SDK fordert weiterhin eine Werbung für die automatisch gecachte Platzierung an. Bei allen anderen Platzierungen wir die Callback-Methode im Fall von "Load Failed" gerufen (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 für die Platzierung bereit ist, können Sie sie mittels der folgenden 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

Vungle SDK v. 5.3 unterstützt jetzt Flex Feed-Anzeigen. Dies ist das erste Anzeigenformat, das keinen ganzen Bildschirm benötigt. Stattdessen bestimmt der Herausgeber die genauen Maße und Position des Anzeige-Containers innerhalb seiner App. Diese Anzeige-Container bieten Sammlungs- oder Tabellenansicht.

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

Das Anzeigen von Flex Feed-Anzeigen unterscheidet sich von dem von Vollbildanzeigen. Bei Flex Feed-Anzeigen 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 anzeigen. 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, 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 einer Flex Feed-Anzeige, kann der Nutzer die Anzeige des Videos beenden, ohne die Anzeige zu schließen. Dazu müssen sie dem SDK mitteilen, die Anzeige zu beenden, wenn sie nicht mehr angezeigt wird. Hierfür rufen Sie die Funktion finishedDisplayingAd auf.

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 lösen:

// Attach
[[VungleSDK sharedSDK] setDelegate:yourDelegateInstance];
// Lösen
[[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 
//Stellt einen BOOL dar, ob ein Video als vollständig angesehen betrachtet werden kann oder nicht.
@property (nonatomic, readonly) NSNumber *completedView;
//Die Zeit in Sekunden, die der Nutzer das Video angesehen hat.
@property (nonatomic, readonly) NSNumber *playTime;
//Stellt einen BOOL dar, ob der Nutzer auf die Download-Schaltfläche geklickt hat oder nicht.
@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 des Werbungserlebnisses 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 und ein besseres Benutzererlebnis zu genießen. 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 des server-zu-server Callback-Systems 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 Anreiz vorzeitig schließt.

VunglePlayAdOptionKeyIncentivizedAlertBodyText

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

NSString

Zeichenfolge, die als Text des Warndialogfelds verwendet wird, das angezeigt wird, wenn ein Benutzer eine Werbung mit Anreiz 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 Anreiz 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 Anreiz vorzeitig schließt.

Beispielcode:

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!"};

// In dict der Optionen weitergeben, Werbung abspielen
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 Abspielen von Werbungen ohne Ton. Sie können vor der Abgabe 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 das Loggen 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