IMA SDK einrichten

du hast begonnen, deine Videoinhalte mit Anzeigen zu monetarisieren.

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-kompatiblen 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 diesem Leitfaden 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

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

2. IMA SDK zum Xcode-Projekt hinzufügen

CocoaPods ist ein Abhängigkeitsmanager für Xcode-Projekte und die empfohlene Methode zum Installieren des IMA 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 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:

    Objective-C

    source 'https://github.com/CocoaPods/Specs.git'  platform :ios, '12'  target "BasicExample" do   pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end  

    Swift

    source 'https://github.com/CocoaPods/Specs.git'  platform :ios, '12'  target "BasicExample" do   pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end  
  2. Führen Sie im Verzeichnis, das die Podfile-Datei enthält, den Befehl 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).

SDK mit Swift Package Manager installieren

Das Interactive Media Ads SDK unterstützt ab Version 3.18.4 den Swift Package Manager. So importieren Sie das Swift-Paket:

  1. Installieren Sie das IMA SDK Swift-Paket in Xcode über File > Add Package Dependencies... (Datei > Paketabhängigkeiten hinzufügen).

  2. Suchen Sie im Prompt nach dem GitHub-Repository für das IMA iOS SDK Swift-Paket: swift-package-manager-google-interactive-media-ads-ios.

  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.

SDK manuell herunterladen und installieren

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

3. Videoplayer erstellen

Implementieren Sie zuerst einen Videoplayer. Anfangs wird in diesem Player das IMA SDK nicht verwendet und er enthält keine Methode zum Starten der Wiedergabe.

Objective-C

Importieren Sie die Player-Abhängigkeiten:

#import "ViewController.h"  @import AVFoundation; 

Richten Sie die Player-Variablen ein:

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>  /// Content video player. @property(nonatomic, strong) AVPlayer *contentPlayer;  /// Play button. @property(nonatomic, weak) IBOutlet UIButton *playButton;  /// UIView in which we will render our AVPlayer for content. @property(nonatomic, weak) IBOutlet UIView *videoView; 

Videoplayer beim Laden der Ansicht initialisieren:

@implementation ViewController  // The content URL to play. NSString *const kTestAppContentUrl_MP4 =     @"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";  // Ad tag NSString *const kTestAppAdTagUrl = @"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=";  - (void)viewDidLoad {   [super viewDidLoad];    self.playButton.layer.zPosition = MAXFLOAT;    [self setupAdsLoader];   [self setUpContentPlayer]; }  #pragma mark Content Player Setup  - (void)setUpContentPlayer {   // Load AVPlayer with path to our content.   NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];   self.contentPlayer = [AVPlayer playerWithURL:contentURL];    // Create a player layer for the player.   AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];    // Size, position, and display the AVPlayer.   playerLayer.frame = self.videoView.layer.bounds;   [self.videoView.layer addSublayer:playerLayer];    // Set up our content playhead and contentComplete callback.   self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];   [[NSNotificationCenter defaultCenter] addObserver:self                                            selector:@selector(contentDidFinishPlaying:)                                                name:AVPlayerItemDidPlayToEndTimeNotification                                              object:self.contentPlayer.currentItem]; }  - (IBAction)onPlayButtonTouch:(id)sender {   [self requestAds];   self.playButton.hidden = YES; } 

Swift

Importieren Sie die Player-Abhängigkeiten:

import AVFoundation 

Richten Sie die Player-Variablen ein:

class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {   static let contentURL = URL(     string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!    private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)    private lazy var playerLayer: AVPlayerLayer = {     AVPlayerLayer(player: contentPlayer)   }() 

Videoplayer beim Laden der Ansicht initialisieren:

private lazy var videoView: UIView = {   let videoView = UIView()   videoView.translatesAutoresizingMaskIntoConstraints = false   view.addSubview(videoView)    NSLayoutConstraint.activate([     videoView.bottomAnchor.constraint(       equalTo: view.safeAreaLayoutGuide.bottomAnchor),     videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),     videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),     videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),   ])   return videoView }()  // MARK: - View controller lifecycle methods  override func viewDidLoad() {   super.viewDidLoad()    videoView.layer.addSublayer(playerLayer)   adsLoader.delegate = self    NotificationCenter.default.addObserver(     self,     selector: #selector(contentDidFinishPlaying(_:)),     name: .AVPlayerItemDidPlayToEndTime,     object: contentPlayer.currentItem) }  override func viewDidAppear(_ animated: Bool) {   super.viewDidAppear(animated)   playerLayer.frame = videoView.layer.bounds }  override func viewWillTransition(   to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator ) {   coordinator.animate { _ in     // do nothing   } completion: { _ in     self.playerLayer.frame = self.videoView.layer.bounds   } }  // MARK: - Public methods  func playButtonPressed() {   requestAds() } 

4. IMA SDK importieren

So importieren Sie das IMA SDK:

Objective-C

  1. IMA SDK importieren:

    @import GoogleInteractiveMediaAds; 
  2. Erstellen Sie Variablen für die Klassen IMAAdsLoader, IMAAVPlayerContentPlayhead und IMAAdsManager, die in der App verwendet werden:

    // SDK /// Entry point for the SDK. Used to make ad requests. @property(nonatomic, strong) IMAAdsLoader *adsLoader;  /// Playhead used by the SDK to track content video progress and insert mid-rolls. @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead;  /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request. @property(nonatomic, strong) IMAAdsManager *adsManager; 

Swift

  1. IMA SDK importieren:

    import GoogleInteractiveMediaAds  
  2. Erstellen Sie Variablen für die Klassen IMAAdsLoader, IMAAVPlayerContentPlayhead und IMAAdsManager, die in der App verwendet werden:

    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="  private let adsLoader = IMAAdsLoader() private var adsManager: IMAAdsManager?  private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = {   IMAAVPlayerContentPlayhead(avPlayer: contentPlayer) }() 

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

Damit Mid-Roll-Anzeigen ausgeliefert werden können, muss das IMA SDK die aktuelle Position Ihres Videocontents 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.

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

Objective-C

Erstellen Sie die IMAAVPlayerContentPlayhead-Instanz bei der Einrichtung des Players:

// Set up our content playhead and contentComplete callback. self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer]; [[NSNotificationCenter defaultCenter] addObserver:self                                          selector:@selector(contentDidFinishPlaying:)                                              name:AVPlayerItemDidPlayToEndTimeNotification                                            object:self.contentPlayer.currentItem]; 

Erstellen Sie die Methode contentDidFinishPlaying(), um IMAAdsLoader.contentComplete() aufzurufen, wenn die Wiedergabe des Inhalts abgeschlossen ist:

- (void)contentDidFinishPlaying:(NSNotification *)notification {   // Make sure we don't call contentComplete as a result of an ad completing.   if (notification.object == self.contentPlayer.currentItem) {     [self.adsLoader contentComplete];   } } 

Swift

Erstellen Sie den Observer für das Ende des Inhalts bei der Einrichtung des Players:

NotificationCenter.default.addObserver(   self,   selector: #selector(contentDidFinishPlaying(_:)),   name: .AVPlayerItemDidPlayToEndTime,   object: contentPlayer.currentItem) 

Erstellen Sie die Methode contentDidFinishPlaying(), um IMAAdsLoader.contentComplete() aufzurufen, wenn die Wiedergabe des Inhalts abgeschlossen ist:

@objc func contentDidFinishPlaying(_ notification: Notification) {   // Make sure we don't call contentComplete as a result of an ad completing.   if notification.object as? AVPlayerItem == contentPlayer.currentItem {     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] initWithSettings:nil];   self.adsLoader.delegate = self; }  - (void)requestAds {   // Create an ad display container for ad rendering.   IMAAdDisplayContainer *adDisplayContainer =       [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView                                           viewController:self                                           companionSlots:nil];   // Create an ad request with our ad tag, display container, and optional user context.   IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl                                                 adDisplayContainer:adDisplayContainer                                                    contentPlayhead:self.contentPlayhead                                                        userContext:nil];   [self.adsLoader requestAdsWithRequest:request]; } 

Swift

private func requestAds() {   // Create ad display container for ad rendering.   let adDisplayContainer = IMAAdDisplayContainer(     adContainer: videoView, viewController: self, companionSlots: nil)   // Create an ad request with our ad tag, display container, and optional user context.   let request = IMAAdsRequest(     adTagUrl: PlayerContainerViewController.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 Anzeigen-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

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {   // Grab the instance of the IMAAdsManager and set ourselves as the delegate.   self.adsManager = adsLoadedData.adsManager;   self.adsManager.delegate = self;   // Create ads rendering settings to tell the SDK to use the in-app browser.   IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];   adsRenderingSettings.linkOpenerPresentingController = self;   // Initialize the ads manager.   [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings]; }  - (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {   // Something went wrong loading ads. Log the error and play the content.   NSLog(@"Error loading ads: %@", adErrorData.adError.message);   [self.contentPlayer 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    // Create ads rendering settings and tell the SDK to use the in-app browser.   let adsRenderingSettings = IMAAdsRenderingSettings()   adsRenderingSettings.linkOpenerPresentingController = self    // Initialize the ads manager.   adsManager?.initialize(with: adsRenderingSettings) }  func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {   if let message = adErrorData.adError.message {     print("Error loading ads: \(message)")   }   contentPlayer.play() } 

8. Delegierten für die Anzeigenverwaltung einrichten

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

Wiedergabe starten

Warten Sie auf das LOADED-Ereignis, um die Wiedergabe von Inhalten und Anzeigen zu starten. Weitere Informationen finden Sie unter didReceiveAdEvent.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {   // When the SDK notified us that ads have been loaded, play them.   if (event.type == kIMAAdEvent_LOADED) {     [adsManager start];   } } 

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {   // When the SDK notifies us the ads have been loaded, play them.   if event.type == IMAAdEventType.LOADED {     adsManager.start()   } } 

Fehler verarbeiten

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 {   // Something went wrong with the ads manager after ads were loaded. Log the error and play the   // content.   NSLog(@"AdsManager error: %@", error.message);   [self.contentPlayer play]; } 

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {   // Something went wrong with the ads manager after ads were loaded.   // Log the error and play the content.   if let message = error.message {     print("AdsManager error: \(message)")   }   contentPlayer.play() } 

Auf Wiedergabe- und Pausierungsereignisse warten

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 {   // The SDK is going to play ads, so pause the content.   [self.contentPlayer pause]; }  - (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {   // The SDK is done playing ads (at least for now), so resume the content.   [self.contentPlayer play]; } 

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {   // The SDK is going to play ads, so pause the content.   contentPlayer.pause() }  func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {   // The SDK is done playing ads (at least for now), so resume the content.   contentPlayer.play() } 

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 Ihren Anzeigenumsatz auf der iOS-Plattform maximieren möchten, fordern Sie die Berechtigung für App-Transparenz und Tracking an, um die IDFA zu verwenden.