IMA SDK einrichten

Plattform auswählen:HTML5 Android iOS tvOS

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 den clientseitigen IMA SDKs behalten Sie die Kontrolle über die Wiedergabe von Videoinhalten, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separaten Videoplayer wiedergegeben, der über dem Videoplayer für die Inhalte der App positioniert ist.

In dieser Anleitung wird gezeigt, wie Sie das IMA SDK in eine Videoplayer-App einbinden. Wenn Sie sich eine vollständige Beispielintegration ansehen oder ihr folgen möchten, laden Sie BasicExample von GitHub herunter.

IMA-Clientseite – Übersicht

Die clientseitige Implementierung von IMA umfasst vier Haupt-SDK-Komponenten, die in dieser Anleitung beschrieben werden:

  • IMAAdDisplayContainer: Ein Containerobjekt, das angibt, wo IMA Benutzeroberflächenelemente für Anzeigen rendert und die Sichtbarkeit misst, einschließlich Active View und Open Measurement.
  • IMAAdsLoader: Ein Objekt, das Anzeigen anfordert und Ereignisse aus Antworten auf Anzeigenanfragen verarbeitet. Sie sollten nur einen Anzeigen-Loader instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • IMAAdsRequest: Ein Objekt, das eine Anzeigenanfrage definiert. In Anzeigenanfragen wird die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie die Anzeigendimensionen angegeben.
  • IMAAdsManager: Ein Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf Anzeigenereignisse wartet, die vom SDK ausgelöst werden.

Vorbereitung

Für den Start ist Folgendes erforderlich:

1. Neues Xcode-Projekt erstellen

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

2. IMA SDK zum Xcode-Projekt hinzufügen

IMA 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 das IMA SDK Swift-Paket in Xcode, indem Sie zu File > Add Packages… gehen.

  2. Suchen Sie im angezeigten Prompt nach dem GitHub-Repository für das IMA SDK Swift Package:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
    
  3. Wählen Sie die Version des IMA SDK Swift Package 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.

IMA SDK mit CocoaPods installieren

Verwenden Sie CocoaPods, um das IMA SDK zu installieren. Weitere Informationen zur Installation oder Verwendung von CocoaPods finden Sie in der CocoaPods-Dokumentation. Führen Sie nach der Installation von CocoaPods die folgenden Schritte aus:

  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, '15'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0'
    end
    
    
  2. Führen Sie im Verzeichnis mit der Podfile-Datei pod install --repo-update aus.

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

IMA SDK manuell herunterladen und installieren

Wenn Sie CocoaPods nicht verwenden möchten, können Sie das IMA SDK herunterladen und manuell in Ihr Projekt einfügen.

3. IMA SDK importieren

Fügen Sie das IMA-Framework mit einer Importanweisung hinzu.

Objective-C

#import "ViewController.h"
#import <AVKit/AVKit.h>

@import GoogleInteractiveMediaAds;

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

4. Videoplayer erstellen und IMA SDK einbinden

Im folgenden Beispiel wird das IMA SDK initialisiert:

Objective-C

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString =
    @"https://pubads.g.doubleclick.net/gampad/ads?"
    @"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
    @"cust_params=sample_ar%3Dpremidpostlongpod&ciu_szs=300x250&gdfp_req=1&ad_rule=1&"
    @"output=vmap&unviewed_position_start=1&env=vp&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end

@implementation ViewController

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

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

// Add the content video player as a child view controller.
- (void)showContentPlayer {
  [self addChildViewController:self.contentPlayerViewController];
  self.contentPlayerViewController.view.frame = self.view.bounds;
  [self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
  [self.contentPlayerViewController didMoveToParentViewController:self];
}

// Remove and detach the content video player.
- (void)hideContentPlayer {
  // The whole controller needs to be detached so that it doesn't capture resume events from the
  // remote and play content underneath the ad.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}

Swift

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURLString =
    "https://devstreaming-cdn.apple.com/videos/streaming/examples/"
    + "img_bipbop_adv_example_fmp4/master.m3u8"
  static let adTagURLString =
    "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&"
    + "sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&"
    + "unviewed_position_start=1&env=vp&correlator="

  var adsLoader: IMAAdsLoader!
  var adDisplayContainer: IMAAdDisplayContainer!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!
  var adBreakActive = false

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black
    setUpContentPlayer()
    setUpAdsLoader()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    requestAds()
  }

In diesem Beispiel wird viewDidLoad() für die Initialisierung von IMAAdsLoader verwendet und viewDidAppear() fordert Anzeigen an, sobald die Ansicht sichtbar ist. Die Hilfsmethoden showContentPlayer() und hideContentPlayer() steuern die Sichtbarkeit von Inhalten während der Anzeigenwiedergabe.

In diesem Beispiel wird die konstante Variable adTagURLString verwendet, um das VAST-Anzeigen-Tag für die Anzeigenanfrage zu definieren. Außerdem werden die folgenden Komponenten zur Verwaltung des IMA SDK verwendet:

  • adsLoader: Verarbeitet Anzeigenanfragen und ‑antworten. Wir empfehlen, für den Lebenszyklus der App eine einzelne Instanz zu verwenden.
  • adDisplayContainer: Gibt die Ansicht für das Rendern von Anzeigen an.
  • adsManager: Verwaltet die Anzeigenwiedergabe und wartet auf Anzeigenereignisse.
  • contentPlayhead: Verfolgt den Fortschritt von Inhalten, um Mid-Roll-Werbeunterbrechungen auszulösen.
  • adBreakActive: Gibt an, ob eine Werbeunterbrechung wiedergegeben wird, um zu verhindern, dass Nutzer Anzeigen überspringen.

5. Tracker für den Wiedergabeposition und Observer für das Ende des Streams implementieren

Damit Mid-Roll-Anzeigen wiedergegeben werden können, muss das IMA SDK die aktuelle Position Ihres Videoinhalts erfassen. Erstellen Sie dazu eine Klasse, die IMAContentPlayhead implementiert. Wenn Sie ein AVPlayer verwenden, wie in diesem Beispiel gezeigt, stellt das SDK die Klasse IMAAVPlayerContentPlayhead bereit, die dies für Sie übernimmt. Wenn Sie AVPlayer nicht verwenden, müssen Sie IMAContentPlayhead in einer eigenen Klasse implementieren.

Objective-C

- (void)setupContentPlayer {
  // Create a content video player. Create a playhead to track content progress so the SDK knows
  // when to play ads in a VMAP playlist.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;
  self.contentPlayhead =
      [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];

  // Track end of content.
  AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:contentPlayerItem];

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

Swift

func setUpContentPlayer() {
  // Load AVPlayer with path to our content.
  let contentURL = URL(string: ViewController.contentURLString)!
  let player = AVPlayer(url: contentURL)
  playerViewController = AVPlayerViewController()
  playerViewController.player = player

  // Set up our content playhead and contentComplete callback.
  contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
  NotificationCenter.default.addObserver(
    self,
    selector: #selector(ViewController.contentDidFinishPlaying(_:)),
    name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
    object: player.currentItem)

  showContentPlayer()
}

Sie müssen dem SDK auch mitteilen, wann die Wiedergabe Ihrer Inhalte beendet ist, damit Post-Roll-Anzeigen ausgeliefert werden können. Dazu wird contentComplete für IMAAdsLoader mit AVPlayerItemDidPlayToEndTimeNotification aufgerufen.

Objective-C

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Notify the SDK that the postrolls should be played.
  [self.adsLoader contentComplete];
}

- (void)dealloc {
  [[NSNotificationCenter defaultCenter] removeObserver:self];
}

Swift

@objc func contentDidFinishPlaying(_ notification: Notification) {
  adsLoader.contentComplete()
}

6. Anzeigen-Loader initialisieren und Anzeigenanfrage stellen

Wenn Sie eine Reihe von Anzeigen anfordern möchten, müssen Sie eine IMAAdsLoader-Instanz erstellen. Mit diesem Loader können IMAAdsRequest-Objekte verarbeitet werden, die mit einer bestimmten Ad-Tag-URL verknüpft sind.

Als Best Practice sollten Sie während des gesamten Lebenszyklus Ihrer App nur eine Instanz von IMAAdsLoader verwenden. Wenn Sie zusätzliche Anzeigenanfragen stellen möchten, erstellen Sie ein neues IMAAdsRequest-Objekt, verwenden Sie aber dieselbe IMAAdsLoader. Weitere Informationen finden Sie in den IMA SDK-FAQs.

Objective-C

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

- (void)requestAds {
  // Pass the main view as the container for ad display.
  self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
                                                                viewController:self];
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
                                                adDisplayContainer:self.adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

Swift

func setUpAdsLoader() {
  adsLoader = IMAAdsLoader(settings: nil)
  adsLoader.delegate = self
}

func requestAds() {
  // Create ad display container for ad rendering.
  adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view, viewController: self)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: ViewController.adTagURLString,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}

7. Ads Loader-Delegaten einrichten

Bei einem erfolgreichen Ladeereignis ruft IMAAdsLoader die Methode adsLoadedWithData des zugewiesenen Delegates auf und übergibt ihr eine Instanz von IMAAdsManager. Anschließend können Sie den Anzeigenmanager initialisieren, der die einzelnen Anzeigen lädt, wie in der Antwort auf die Ad-Tag-URL definiert.

Außerdem sollten Sie alle Fehler behandeln, die während des Ladevorgangs auftreten können. Wenn Anzeigen nicht geladen werden, muss die Medienwiedergabe ohne Anzeigen fortgesetzt werden, damit die Nutzererfahrung nicht beeinträchtigt wird.

Objective-C

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

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

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  adsManager = adsLoadedData.adsManager
  adsManager.delegate = self
  adsManager.initialize(with: nil)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
  showContentPlayer()
  playerViewController.player?.play()
}

8. Delegierten für die Anzeigenverwaltung einrichten

Schließlich benötigt der Anzeigenmanager einen eigenen Delegaten, um Ereignisse und Statusänderungen zu verwalten. Die IMAAdManagerDelegate enthält Methoden zum Verarbeiten von Anzeigenereignissen und ‑fehlern sowie Methoden zum Starten und Pausieren der Wiedergabe von Videoinhalten.

Wiedergabe starten

Es gibt viele Ereignisse, die mit der Methode didReceiveAdEvent verarbeitet werden können. In diesem einfachen Beispiel wird auf das LOADED-Ereignis gewartet, um den Anzeigenmanager anzuweisen, die Wiedergabe von Inhalten und Anzeigen zu starten. Das IMA SDK löst das Ereignis ICON_FALLBACK_IMAGE_CLOSED aus, wenn der Nutzer ein Dialogfeld für das Symbol-Fallback schließt, nachdem er auf ein Symbol getippt hat. Danach wird die Anzeigenwiedergabe fortgesetzt.

Objective-C

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  switch (event.type) {
    case kIMAAdEvent_LOADED: {
      // Play each ad once it has loaded.
      [adsManager start];
      break;
    }
    case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
      // Resume ad after user has closed dialog.
      [adsManager resume];
      break;
    }
    default:
      break;
  }
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  switch event.type {
  case IMAAdEventType.LOADED:
    // Play each ad once it has been loaded.
    adsManager.start()
  case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
    // Resume playback after the user has closed the dialog.
    adsManager.resume()
  default:
    break
  }
}

Fehlerbehebung

Fügen Sie auch einen Handler für Anzeigenfehler hinzu. Wenn ein Fehler auftritt, wie im vorherigen Schritt, setze die Wiedergabe fort.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing content.
  NSLog(@"AdsManager error: %@", error.message);
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Fall back to playing content
  print("AdsManager error: \(error.message ?? "No error message available.")")
  showContentPlayer()
  playerViewController.player?.play()
}

Wiedergabe- und Pausenereignisse auslösen

Die letzten beiden Delegatenmethoden, die Sie implementieren müssen, werden verwendet, um Wiedergabe- und Pausierungsereignisse für die zugrunde liegenden Videoinhalte auszulösen, wenn das IMA SDK dies anfordert. Wenn das Pausieren und Abspielen auf Anfrage ausgelöst wird, verpasst der Nutzer keine Teile des Videoinhalts, wenn Anzeigen eingeblendet werden.

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
  // Trigger an update to send focus to the ad display container.
  self.adBreakActive = YES;
  [self setNeedsFocusUpdate];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
  // Trigger an update to send focus to the content player.
  self.adBreakActive = NO;
  [self setNeedsFocusUpdate];
}

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // Pause the content for the SDK to play ads.
  playerViewController.player?.pause()
  hideContentPlayer()
  // Trigger an update to send focus to the ad display container.
  adBreakActive = true
  setNeedsFocusUpdate()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // Resume the content since the SDK is done playing ads (at least for now).
  showContentPlayer()
  playerViewController.player?.play()
  // Trigger an update to send focus to the content player.
  adBreakActive = false
  setNeedsFocusUpdate()
}

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

Nächste Schritte

Wenn Sie den Werbeumsatz auf der tvOS-Plattform maximieren möchten, fordern Sie die App-Transparenz- und Tracking-Berechtigung an, um die IDFA zu verwenden.