Einführung in das IMA DAI SDK

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

Wählen Sie die gewünschte dynamische Anzeigenbereitstellungslösung aus.

Pod-Auslieferung mit dynamischer Anzeigenbereitstellung

In dieser Anleitung wird gezeigt, wie du das IMA DAI SDK in eine einfache Videoplayer-App einbindest. Wenn du dir eine fertige Beispielintegration ansehen oder ansehen möchtest, lade das PodServingExample von GitHub herunter.

IMA DAI – Übersicht

Die Implementierung von IMA-DA umfasst vier Haupt-SDK-Komponenten, wie in diesem Leitfaden gezeigt:

• 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 von Streamanfragen ausgelöst werden. Sie sollten nur einen Anzeigen-Lademechanismus instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
• IMAStreamRequest – entweder IMAPodVODStreamRequest oder IMAPodStreamRequest.
• IMAStreamManager: Ein Objekt, das Streams für die dynamische Anzeigenbereitstellung und Interaktionen mit dem DAI-Backend verarbeitet. Der Streammanager verarbeitet auch Tracking-Pings und leitet Stream- und Anzeigenereignisse an den Publisher weiter.

Außerdem musst du einen benutzerdefinierten VTP-Handler implementieren, um Streams mit Pod-Auslieferung abzuspielen. Dieser benutzerdefinierte VTP-Handler sendet die Stream-ID zusammen mit allen anderen Informationen an deinen VTP, die für die Rückgabe eines Stream-Manifests mit Inhalten und zusammengefügten Anzeigen erforderlich sind. Ihre VTP enthält eine Anleitung zum Implementieren Ihres benutzerdefinierten VTP-Handlers.

Vorbereitung

Für den Start ist Folgendes erforderlich:

• Xcode 13 oder höher
• CocoaPods (bevorzugt), Swift Package Manager oder eine heruntergeladene Kopie des IMA DAI SDK für iOS

Außerdem benötigst du die Parameter, mit denen dein Stream vom IMA SDK angefordert wird.

Neues Xcode-Projekt erstellen

Erstellen Sie in Xcode ein neues iOS-Projekt mit Objective-C namens „PodServingExample“.

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 (bevorzugt)

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 du CocoaPods installiert hast, kannst du das IMA DAI SDK mithilfe der folgenden Anleitung installieren:

1. Erstellen Sie im selben Verzeichnis wie die Datei PodServingExample.xcodeproj eine Textdatei namens Podfile und fügen Sie die folgende Konfiguration hinzu:

   Podfile
   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14'
   
   target 'PodServingExample' do
     pod 'GoogleAds-IMA-iOS-SDK'
   end
   Podfile

2. Führen Sie im Verzeichnis mit der Podfile Folgendes aus:

   pod install --repo-update

SDK mit dem Swift Package Manager installieren

Das Interactive Media Ads SDK unterstützt ab Version 3.18.4 den Swift Package Manager. Folgen Sie der Anleitung unten, um das Swift-Paket zu importieren.

1. Installiere in Xcode das IMA DAI SDK-Swift-Paket. Gehe dazu zu File > Add Packages (Datei > Pakete hinzufügen).

2. Suche in der angezeigten Aufforderung nach dem GitHub-Repository für das IMA DAI SDK Swift-Paket:

   https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
   

3. Wähle die Version des IMA DAI SDK Swift-Pakets aus, die du verwenden möchtest. Für neue Projekte empfehlen wir die Option Bis zur nächsten Hauptversion.

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 im Artikel von Apple.

SDK manuell herunterladen und installieren

Wenn Sie den 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 einen Videoplayer in Ihrem Haupt-View-Controller, indem Sie einen AV-Player in einer UI-Ansicht einbetten. Das IMA SDK verwendet die UI-Ansicht, um Anzeigen-UI-Elemente anzuzeigen.

#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

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

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end
ViewController.m

Anzeigen-Ladeprogramm initialisieren

Importiere das IMA SDK in deinen View Controller und verwende die Protokolle IMAAdsLoaderDelegate und IMAStreamManagerDelegate, um Ereignisse des Anzeigen-Ladeprogramms und des Stream-Managers zu verarbeiten.

Füge diese privaten Properties hinzu, um wichtige IMA SDK-Komponenten zu speichern:

• IMAAdsLoader: Verwaltet Streamanfragen während der gesamten Lebensdauer deiner App.
• IMAAdDisplayContainer: Verwaltet das Einfügen und Verwalten von Elementen der Anzeigenbenutzeroberfläche.
• IMAAVPlayerVideoDisplay: Vermittelt die Kommunikation zwischen dem IMA SDK und dem Mediaplayer und verarbeitet zeitgesteuerte Metadaten.
• IMAStreamManager: Verwaltet die Streamwiedergabe und löst anzeigebezogene Ereignisse aus.

Initiiere den Anzeigen-Lademechanismus, den Anzeigen-Displaycontainer und das Videodisplay, nachdem der Videofeed geladen wurde.

@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}
ViewController.m

Streamanfrage stellen

Wenn ein Nutzer auf die Wiedergabeschaltfläche drückt, sende eine neue Streamanfrage. Verwenden Sie die Klasse IMAPodStreamRequest für Livestreams. Verwende für VOD-Streams die Klasse IMAPodVODStreamRequest.

Die Streamanfrage erfordert deine Streamparameter sowie eine Referenz auf deinen Anzeigendisplaycontainer und dein Videodisplay.

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request.
  IMAStreamRequest *request;
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the network code and custom asset key with your values.
    request = [[IMAPodStreamRequest alloc] initWithNetworkCode:kNetworkCode
                                                customAssetKey:kCustomAssetKey
                                            adDisplayContainer:adDisplayContainer
                                                  videoDisplay:self.videoDisplay
                                         pictureInPictureProxy:nil
                                                   userContext:nil];
  } else {
    // VOD request. Replace the network code with your value.
    request = [[IMAPodVODStreamRequest alloc] initWithNetworkCode:@kNetworkCode
                                               adDisplayContainer:adDisplayContainer
                                                     videoDisplay:self.videoDisplay
                                            pictureInPictureProxy:nil
                                                      userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

Auf Stream-Ladevorgänge warten

Die Klasse IMAAdsLoader ruft die Methoden IMAAdsLoaderDelegate bei erfolgreicher Initialisierung oder Fehler der Streamanfrage auf.

Legen Sie in der Delegating-Methode adsLoadedWithData den Wert für IMAStreamManagerDelegate fest. Übergebe die Stream-ID an deinen benutzerdefinierten VTP-Handler und rufe die Manifest-URL des Streams ab. Lade bei Livestreams die Manifest-URL in deinen Video-Bildschirm und starte die Wiedergabe. Übergebe bei VOD-Streams die Manifest-URL an die loadThirdPartyStream-Methode des Stream-Managers. Bei dieser Methode werden Anzeigenereignisdaten von Ad Manager 360 angefordert, die Manifest-URL geladen und die Wiedergabe gestartet.

Protokollieren Sie den Fehler in der delegierten Methode failedWithErrorData. Optional: Wiedergabe des Sicherungsstreams Best Practices für dynamische Anzeigenbereitstellung

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;

  // Build the Pod serving Stream URL.
  NSString *streamID = adsLoadedData.streamManager.streamId;
  // Your custom VTP handler takes the stream ID and returns the stream manifest URL.
  NSString *urlString = gCustomVTPHandler(streamID);
  NSURL *streamUrl = [NSURL URLWithString:urlString];
  if (kStreamType == StreamTypeLive) {
    // Load live streams directly into the AVPlayer.
    [self.videoDisplay loadStream:streamUrl withSubtitles:@[]];
    [self.videoDisplay play];
  } else {
    // Load VOD streams using the `loadThirdPartyStream` method in IMA SDK's stream manager.
    // The stream manager loads the stream, requests metadata, and starts playback.
    [self.streamManager loadThirdPartyStream:streamUrl streamSubtitles:@[]];
  }
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the backup content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}
ViewController.m

Benutzerdefinierten VTP-Handler implementieren

Der benutzerdefinierte VTP-Handler sendet die Stream-ID des Betrachters zusammen mit allen anderen Informationen, die dein VTP benötigt, um ein Stream-Manifest zurückzugeben, das sowohl Inhalte als auch zusammengeführte Anzeigen enthält, an deinen VTP. Ihr VTP enthält eine spezifische Anleitung zur Implementierung Ihres benutzerdefinierten VTP-Handlers.

Eine VTP kann beispielsweise eine Manifest-Vorlagen-URL mit dem Makro [[STREAMID]] enthalten. In diesem Beispiel fügt der Handler die Stream-ID anstelle des Makros ein und gibt die resultierende Manifest-URL zurück.

/// Custom VTP Handler.
///
/// Returns the stream manifest URL from the video technical partner or manifest manipulator.
static NSString *(^gCustomVTPHandler)(NSString *) = ^(NSString *streamID) {
  // Insert synchronous code here to retrieve a stream manifest URL from your video tech partner
  // or manifest manipulation server.
  // This example uses a hardcoded URL template, containing a placeholder for the stream
  // ID and replaces the placeholder with the stream ID.
  NSString *manifestUrl = @"YOUR_MANIFEST_URL_TEMPLATE";
  return [manifestUrl stringByReplacingOccurrencesOfString:@"[[STREAMID]]"
                                                withString:streamID];
};
ViewController.m

Auf Anzeigenereignisse warten

Die IMAStreamManager ruft die Methoden IMAStreamManagerDelegate auf, um Streamereignisse und ‑fehler an Ihre Anwendung weiterzuleiten.

Protokollieren Sie in diesem Beispiel die wichtigsten Anzeigenereignisse in der Konsole:

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

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}
ViewController.m

IMA-DAI-Assets bereinigen

Wenn du die Streamwiedergabe beenden, alle Anzeigen-Tracking-Mechanismen stoppen und alle geladenen Stream-Assets freigeben möchtest, ruf IMAStreamManager.destroy() auf.

Führen Sie Ihre App aus. Wenn die Ausführung erfolgreich war, können Sie Google-Streams für die dynamische Anzeigenbereitstellung mit dem IMA SDK anfordern und wiedergeben. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Anleitungen in der linken Seitenleiste oder in den Beispielen auf GitHub.