IMA SDK für die dynamische Anzeigenbereitstellung einrichten

Mit den IMA SDKs lassen sich Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. Mit IMA SDKs können Anzeigen von jedem VAST-konformen Ad-Server angefordert und die Anzeigenwiedergabe in Ihren Apps verwaltet werden. Mit IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Contentvideos – entweder VOD- oder Liveinhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie das Umschalten zwischen Anzeigen- und Inhaltsvideo in Ihrer App nicht verwalten müssen.

Wählen Sie die DAI-Lösung aus, die Sie interessiert

Komplettservice für die dynamische Anzeigenbereitstellung

In dieser Anleitung wird gezeigt, wie Sie das IMA DAI SDK in eine einfache Videoplayer-App einbinden. Wenn Sie sich ein vollständiges Beispiel für die Einbindung ansehen oder die Anleitung mit einem solchen Beispiel durcharbeiten möchten, laden Sie BasicExample von GitHub herunter.

IMA DAI – Übersicht

Die Implementierung von IMA DAI umfasst drei Haupt-SDK-Komponenten, wie in diesem Leitfaden beschrieben:

  • IMAAdDisplayContainer: Ein Containerobjekt, das sich über dem Videowiedergabeelement befindet und die UI-Elemente der Anzeige enthält.
  • IMAAdsLoader: Ein Objekt, das Streams anfordert und Ereignisse verarbeitet, die durch Antwortobjekte für Streamanfragen ausgelöst werden. Sie sollten nur einen Anzeigen-Loader instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • IMAStreamRequest: entweder ein IMAVODStreamRequest- oder ein IMALiveStreamRequest-Objekt, das eine Streamanfrage definiert. Streamanfragen können entweder für Video-on-Demand- oder Livestreams erfolgen. In Livestream-Anfragen wird ein Asset-Schlüssel angegeben, in VOD-Anfragen eine CMS-ID und eine Video-ID. Beide Anfragetypen können optional einen API-Schlüssel enthalten, der für den Zugriff auf die angegebenen Streams erforderlich ist, sowie einen Google Ad Manager-Netzwerkcode, damit das IMA SDK Anzeigen-IDs gemäß den Google Ad Manager-Einstellungen verarbeiten kann.
  • IMAStreamManager: Ein Objekt, das Streams für die dynamische Anzeigenbereitstellung und Interaktionen mit dem Backend für die dynamische Anzeigenbereitstellung verarbeitet. Der Stream-Manager verarbeitet auch Tracking-Pings und leitet Stream- und Anzeigenereignisse an den Publisher weiter.

Vorbereitung

Für den Start ist Folgendes erforderlich:

Neues Xcode-Projekt erstellen

Erstellen Sie in Xcode ein neues tvOS-Projekt mit Objective-C. Verwenden Sie BasicExample als Projektnamen.

IMA DAI SDK zum Xcode-Projekt hinzufügen

Verwenden Sie eine dieser drei Methoden, um das IMA DAI SDK zu installieren.

SDK mit CocoaPods installieren (empfohlen)

CocoaPods ist ein Abhängigkeitsmanager für Xcode-Projekte und die empfohlene Methode zum Installieren des IMA DAI SDK. Weitere Informationen zur Installation oder Verwendung von CocoaPods finden Sie in der CocoaPods-Dokumentation. Nachdem Sie CocoaPods installiert haben, folgen Sie dieser Anleitung, um das IMA DAI SDK zu installieren:

  1. Erstellen Sie im selben Verzeichnis wie die Datei BasicExample.xcodeproj eine Textdatei mit dem Namen Podfile und fügen Sie die folgende Konfiguration hinzu:

    source 'https://github.com/CocoaPods/Specs.git'
    platform :tvos, '14'
    target "BasicExample" do
      pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.15.1'
    end
    
  2. Führen Sie im Verzeichnis, das die Podfile-Datei enthält, Folgendes aus:

    pod install --repo-update`
  3. Prüfen Sie, ob die Installation erfolgreich war, indem Sie die Datei BasicExample.xcworkspace öffnen und prüfen, ob sie zwei Projekte enthält: BasicExample und Pods (die von CocoaPods installierten Abhängigkeiten).

SDK mit Swift Package Manager installieren

Das Interactive Media Ads SDK unterstützt ab Version 4.8.2 den Swift Package Manager. Gehen Sie so vor, um das Swift-Paket zu importieren.

  1. Installieren Sie in Xcode das GoogleInteractiveMediaAds-Swift-Paket, indem Sie zu File > Add Packages gehen.

  2. Suchen Sie im angezeigten Prompt nach dem GitHub-Repository für das GoogleInteractiveMediaAds Swift-Paket:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
    
  3. Wählen Sie die Version des GoogleInteractiveMediaAds Swift-Pakets aus, die Sie verwenden möchten. Für neue Projekte empfehlen wir die Verwendung von Up to Next Major Version.

Wenn Sie fertig sind, löst Xcode Ihre Paketabhängigkeiten auf und lädt sie im Hintergrund herunter. Weitere Informationen zum Hinzufügen von Paketabhängigkeiten finden Sie in diesem Artikel von Apple.

SDK manuell herunterladen und installieren

Wenn Sie Swift Package Manager oder CocoaPods nicht verwenden möchten, können Sie das IMA DAI SDK herunterladen und Ihrem Projekt manuell hinzufügen.

Einfachen Videoplayer erstellen

Implementieren Sie zuerst einen einfachen Videoplayer. Dieser Player verwendet anfangs weder das IMA DAI SDK noch enthält er eine Methode zum Auslösen der Wiedergabe.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];
}

@end

SDK importieren und Stubs für die IMA-Interaktion hinzufügen

Nachdem Sie das IMA DAI SDK Ihrem Projekt hinzugefügt haben, importieren Sie das SDK und fügen Sie Stubs für die primären IMA-Interaktionspunkte hinzu.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];

  [self attachAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

IMAAdsLoader implementieren

Als Nächstes instanziieren Sie IMAAdsLoader und hängen die Ansicht des Anzeigencontainers an die Ansichtshierarchie an.

ViewController.m

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
  self.adsLoader.delegate = self;
}

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}

Streaminganfrage stellen

Erstellen Sie einige Konstanten, um die Streaminformationen zu speichern, und implementieren Sie dann die Streamanfragefunktion, um die Anfrage zu stellen.

ViewController.m

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                                     networkCode:kNetworkCode
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                              networkCode:kNetworkCode
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}

Stream-Ereignisse verarbeiten

Die IMAAdsLoader- und IMAStreamManager-Ereignisse werden ausgelöst, um die Initialisierung, Fehler und Änderungen des Streamstatus zu verarbeiten. Diese Ereignisse werden über die Protokolle IMAAdsLoaderDelegate und IMAStreamManagerDelegate ausgelöst. Hören Sie auf ein Ereignis, das angibt, dass Anzeigen geladen wurden, und initialisieren Sie den Stream. Wenn eine Anzeige nicht geladen werden kann, wird stattdessen ein Backup-Stream wiedergegeben.

ViewController.m

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}

#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

Logging- und Fehlerereignisse verarbeiten

Es gibt mehrere Ereignisse, die vom Stream-Manager-Delegate verarbeitet werden können. Bei einfachen Implementierungen sind die wichtigsten Anwendungsfälle jedoch das Protokollieren von Ereignissen, das Verhindern von Suchvorgängen während der Anzeigenwiedergabe und die Fehlerbehandlung.

ViewController.m

#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"StreamManager event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
                         event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
                         event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      // Prevent user seek through when an ad starts and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}

@end

Geschafft! Sie fordern jetzt Anzeigen mit dem IMA DAI SDK an und präsentieren sie. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.