Einstieg

Mit IMA SDKs können Sie Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. IMA SDKs können Anzeigen von beliebigen <ph type="x-smartling-placeholder"></ph> VAST-kompatiblen Ad-Server bereitstellen und die Anzeigenwiedergabe in Ihren Apps verwalten. Mit clientseitigen IMA SDKs Sie behalten die Kontrolle über die Videowiedergabe, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separater Videoplayer, der sich über dem Videoplayer der App befindet.

In diesem Leitfaden wird gezeigt, wie Sie das IMA SDK in einen einfachen Videoplayer integrieren. Wenn Sie sich eine fertige Stichprobe ansehen oder mit ihr einhergehen möchten -Integration, laden Sie die BasicExample von GitHub

Clientseitiges IMA – Übersicht

Für die clientseitige Implementierung von IMA sind vier SDK-Hauptkomponenten erforderlich: die in diesem Leitfaden erläutert werden:

• IMAAdDisplayContainer: Ein Containerobjekt, in dem Anzeigen gerendert werden.
• IMAAdsLoader: Ein Objekt, das Anzeigen anfordert und Ereignisse aus Antworten auf Anzeigenanfragen verarbeitet. Sie sollten nur ein Anzeigenladeprogramm instanziieren, das während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
• IMAAdsRequest: Ein Objekt, das eine Anzeigenanfrage definiert. In den Anzeigenanfragen wird die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie Anzeigenabmessungen.
• IMAAdsManager: Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf die Anzeige wartet Ereignisse, die vom SDK ausgelöst werden.

Vorbereitung

Für den Start ist Folgendes erforderlich:

• Xcode 13 oder höher
• CocoaPods (bevorzugt), Swift Package Manager oder ein heruntergeladene Kopie der IMA SDK für tvOS

1. Neues Xcode-Projekt erstellen

Erstellen Sie in Xcode mit Objective-C oder Swift ein neues tvOS-Projekt. Verwenden Sie BasicExample als Projektname verwenden.

2. IMA SDK zum Xcode-Projekt hinzufügen

SDK mit CocoaPods installieren (bevorzugt)

CocoaPods ist ein Abhängigkeitsmanager für Xcode-Projekte und wird empfohlen. um das IMA SDK zu installieren. Weitere Informationen zur Installation oder Verwendung Informationen zu CocoaPods finden Sie in der CocoaPods-Dokumentation. Sobald Sie CocoaPods installiert haben, können Sie wie unten beschrieben vorgehen, um das IMA SDK zu installieren:

1. Erstellen Sie im selben Verzeichnis wie die Datei BasicExample.xcodeproj einen Text. Podfile und fügen die folgende Konfiguration hinzu:

   source 'https://github.com/CocoaPods/Specs.git'
   platform :tvos, '14'
   target "BasicExample" do
     pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0'
   end
   

2. Führen Sie im Verzeichnis, das die Podfile-Datei enthält, den Befehl pod install --repo-update aus.

3. Überprüfen Sie, ob die Installation erfolgreich war, indem Sie die BasicExample.xcworkspace erstellen und bestätigen, dass 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 das Swift-Paket. Google Ads-Kontoverwaltung ab Version 4.8.2. Folgen Sie um das Swift-Paket zu importieren.

1. Installieren Sie in Xcode das IMA SDK Swift Package, indem Sie Datei > Pakete hinzufügen...

2. Suchen Sie in der angezeigten Aufforderung nach dem IMA SDK Swift Package GitHub Repository:

   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 Bis zur nächsten Hauptversion.

Sobald Sie fertig sind, löst Xcode Ihre Paketabhängigkeiten auf werden im Hintergrund heruntergeladen. Weitere Informationen zum Hinzufügen eines Pakets Abhängigkeiten, siehe Artikel von Apple

SDK manuell herunterladen und installieren

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

3. Einfachen Videoplayer erstellen

Implementieren Sie zuerst einen einfachen Videoplayer. Anfangs verwendet dieser Player nicht die IMA SDK verwenden und noch keine Methode zum Auslösen der Wiedergabe enthält.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";

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

@implementation ViewController

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

- (void)setupContentPlayer {
  // Create a content video player.
  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;

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

// 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 events from the remote.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}

@end
      

import AVFoundation
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var playerViewController: AVPlayerViewController!

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

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

    showContentPlayer()
  }

  func showContentPlayer() {
    self.addChild(playerViewController)
    playerViewController.view.frame = self.view.bounds
    self.view.insertSubview(playerViewController.view, at: 0)
    playerViewController.didMove(toParent:self)
  }

  func hideContentPlayer() {
    // The whole controller needs to be detached so that it doesn't capture  events from the remote.
    playerViewController.willMove(toParent:nil)
    playerViewController.view.removeFromSuperview()
    playerViewController.removeFromParent()
  }
}
      

4. IMA SDK importieren

Fügen Sie als Nächstes das IMA-Framework mit einer Importanweisung unter dem vorhandenen Datenimport und -import.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
      

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
      

5. Abspielkopf-Tracker für Inhalte und End-of-Stream-Beobachter implementieren

Damit Mid-Roll-Anzeigen wiedergegeben werden können, muss das IMA SDK die aktuelle Position Ihres Videocontents. Erstellen Sie dazu eine Klasse, die IMAContentPlayhead Wenn Sie ein AVPlayer verwenden, wie in diesem Beispiel, Das SDK stellt die IMAAVPlayerContentPlayhead-Klasse bereit, die das für dich erledigt. Wenn Sie AVPlayer nicht verwenden, müssen Sie IMAContentPlayhead auf eine Klasse für sich.

Außerdem musst du dem SDK mitteilen, wenn die Wiedergabe deiner Inhalte abgeschlossen ist, damit es Post-Roll-Anzeigen schalten. Rufen Sie dazu contentComplete auf der IMAAdsLoader, mit AVPlayerItemDidPlayToEndTimeNotification.

ViewController.m

...

@interface ViewController ()
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

...

- (void)setupContentPlayer {
  // Create a content video player.
  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];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {}

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

@end
      

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

...

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

    // Set up your 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()
  }

...

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

6. Anzeigenladeprogramm initialisieren und eine Anzeigenanfrage stellen

Um eine Gruppe von Anzeigen anzufordern, müssen Sie eine IMAAdsLoader-Instanz erstellen. Mit diesem Loader können IMAAdsRequest-Objekte verarbeitet werden, die mit einem die angegebene Anzeigen-Tag-URL enthält.

Als Best Practice sollten Sie nur eine Instanz von IMAAdsLoader für die gesamte Lebenszyklus Ihrer App. Wenn Sie weitere Anzeigenanfragen stellen möchten, erstellen Sie eine neue IMAAdsRequest-Objekt, aber verwenden Sie dasselbe IMAAdsLoader-Objekt. Weitere Informationen Häufig gestellte Fragen zum IMA SDK.

ViewController.m

...

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&impl=s&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

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

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

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

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

...

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

...

@end
      

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
  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&impl=s&correlator="

  var adsLoader: IMAAdsLoader!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

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

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

...

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

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

    adsLoader.requestAds(with: request)
  }

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

7. Bevollmächtigten für das Laden von Anzeigen einrichten

Bei einem erfolgreichen Ladeereignis ruft der IMAAdsLoader die adsLoadedWithData auf. des zugewiesenen Delegaten und übergeben Sie eine Instanz von IMAAdsManager. Ich kann dann den Ad Manager initialisieren, der die Einzelanzeigen gemäß durch die Antwort auf die Anzeigen-Tag-URL.

Behandeln Sie außerdem Fehler, die beim Laden . Wenn die Anzeigen nicht geladen werden, sorgen Sie dafür, dass die Medienwiedergabe ohne Anzeigen geschaltet werden, damit der Nutzer nicht gestört wird.

ViewController.m

...

@interface ViewController () <IMAAdsLoaderDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

...

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

...

#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 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];
}

@end
      

...

class ViewController: UIViewController, IMAAdsLoaderDelegate {

...

  var adsLoader: IMAAdsLoader!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

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

...

  // MARK: - IMAAdsLoaderDelegate

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    adsManager = adsLoadedData.adsManager
    adsManager.initialize(with: nil)
  }

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

8. Ad Manager-Bevollmächtigten einrichten

Für die Verwaltung von Ereignissen und Statusänderungen benötigt der Google Ad Manager für sich nutzen. IMAAdManagerDelegate bietet Methoden zum Verarbeiten von Anzeigenereignissen und -fehlern. sowie Methoden zum Auslösen der Wiedergabe und des Pausierens Ihres Videocontents.

Wiedergabe wird gestartet

Es gibt viele Ereignisse, die mit der Methode didReceiveAdEvent verarbeitet werden können. Bei diesem einfachen Beispiel warten Sie einfach auf das LOADED-Ereignis, um die Anzeigen um die Wiedergabe von Inhalten und Anzeigen zu starten.

ViewController.m

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

...

- (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];
}

...

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // Play each ad once it has loaded.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

...
      

...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {

...

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

...

  // MARK: - IMAAdsManagerDelegate

  func adsManager(_ adsManager: IMAAdsManager!, didReceive event: IMAAdEvent!) {
    // Play each ad once it has been loaded
    if event.type == IMAAdEventType.LOADED {
      adsManager.start()
    }
  }

...
      

Fehlerbehebung

Fügen Sie außerdem einen Handler für Anzeigenfehler hinzu. Wenn ein Fehler auftritt, wie in der die Wiedergabe des Inhalts fortsetzen.

ViewController.m

...

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

...

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

Wiedergabe- und Pausenereignisse auslösen

Die letzten beiden Delegatmethoden, die Sie implementieren müssen, werden verwendet, um die Wiedergabe auszulösen und Ereignisse im zugrunde liegenden Videocontent pausieren, wenn dies vom IMA SDK angefordert wird Durch das Auslösen der Pause- und Wiedergabe-Funktion auf Anforderung wird verhindert, dass dem Nutzer Teile fehlen. des Videos, wenn Anzeigen eingeblendet werden.

ViewController.m

...

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}

@end
      

...

  func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager!) {
    // Pause the content for the SDK to play ads.
    playerViewController.player?.pause()
    hideContentPlayer()
  }

  func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager!) {
    // Resume the content since the SDK is done playing ads (at least for now).
    showContentPlayer()
    playerViewController.player?.play()
  }
}
      

Fertig! Sie fordern jetzt Anzeigen mit dem IMA SDK an und schalten diese ein. Weitere Informationen Informationen zu zusätzlichen SDK-Funktionen finden Sie in den anderen Leitfäden oder in den Beispiele auf GitHub

Nächste Schritte

Wenn Sie den Werbeumsatz auf der tvOS-Plattform maximieren möchten, fordern Sie die Berechtigung für App-Transparenz und -Tracking zur Verwendung von IDFA an.