Mit IMA SDKs können Sie ganz einfach Multimediaanzeigen in Ihre Websites und Apps einbinden. IMA SDKs can Anzeigen von jedem VAST-konformen Ad-Server anfordern und die Anzeigenwiedergabe in Ihren Apps verwalten. Mit 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 eine vollständige Beispiel integration ansehen oder nachvollziehen möchten, laden Sie das BasicExample von GitHub herunter.
Übersicht über die clientseitige IMA-Implementierung
Die clientseitige IMA-Implementierung umfasst vier Hauptkomponenten des SDK. In dieser Anleitung werden diese Komponenten vorgestellt:
IMAAdDisplayContainer: Ein Containerobjekt, das angibt, wo IMA UI-Elemente 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 ein Anzeigenladeprogramm instanziieren, das 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 Anzeigengrößen angegeben.IMAAdsManager: Ein Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf Anzeigen ereignisse wartet, die vom SDK ausgelöst werden.
Vorbereitung
Für den Start ist Folgendes erforderlich:
- Xcode 13 oder höher
- Methode zum Installieren des IMA SDK:
- Empfohlen: Swift Package Manager
- CocoaPods
- Eine heruntergeladene Kopie des IMA SDK für tvOS
1. Neues Xcode-Projekt erstellen
Erstellen Sie in Xcode ein neues tvOS-Projekt mit Objective-C oder Swift. Verwenden Sie BasicExample als Projektnamen.
2. IMA SDK zum Xcode-Projekt hinzufügen
Wählen Sie eine bevorzugte Methode aus, um das IMA SDK zu installieren.
Empfohlen: IMA SDK mit Swift Package Manager installieren
Das Interactive Media Ads SDK unterstützt Swift Package Manager ab Version 4.8.2. Führen Sie die folgenden Schritte aus, um das Swift-Paket zu importieren.
Installieren Sie in Xcode das IMA SDK Swift Package, indem Sie zu File > Add Packages... (Datei > Pakete hinzufügen...) gehen.
Suchen Sie in der angezeigten Eingabeaufforderung nach dem GitHub-Repository für das IMA SDK Swift Package:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosWählen Sie die Version des IMA SDK Swift Package aus, die Sie verwenden möchten. Für neue Projekte empfehlen wir die Option Up to Next Major Version (Bis zur nächsten Hauptversion).
Wenn Sie fertig sind, löst Xcode die Paketabhängigkeiten auf und lädt sie im Hintergrund herunter. Weitere Informationen zum Hinzufügen von Paket abhängigkeiten finden Sie im 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. Nachdem Sie CocoaPods installiert haben, gehen Sie so vor:
Erstellen Sie im selben Verzeichnis wie die Datei BasicExample.xcodeproj eine Text datei 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' endFühren Sie im Verzeichnis mit der Podfile-Datei den Befehl
pod install --repo-updateaus.Prüfen Sie, ob die Installation erfolgreich war, indem Sie die Datei BasicExample.xcworkspace öffnen und bestätigen, dass sie zwei Projekte enthält: BasicExample und Pods (die von CocoaPods installierten Abhängigkeiten).
IMA SDK manuell herunterladen und installieren
Wenn Sie Swift Package Manager nicht verwenden möchten, laden Sie das IMA SDK herunter und fügen Sie es manuell Ihrem Projekt hinzu.
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 IMAAdsLoader mit viewDidLoad() initialisiert und mit viewDidAppear() werden Anzeigen angefordert, sobald die Ansicht sichtbar ist. Mit den Hilfsmethoden showContentPlayer() und hideContentPlayer() wird die Sichtbarkeit von Inhalten während der Anzeigenwiedergabe umgeschaltet.
In diesem Beispiel wird die konstante Variable adTagURLString verwendet, um das VAST-Anzeigen-Tag für die Anzeigenanfrage zu definieren, und die folgenden Komponenten werden verwendet, um das IMA SDK zu verwalten:
adsLoader: Verarbeitet Anzeigenanfragen und -antworten. Wir empfehlen, während des gesamten Lebenszyklus der App nur eine 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 der Wiedergabe von Inhalten, um Mid-Roll-Werbeunterbrechungen auszulösen.adBreakActive: Gibt an, ob eine Werbeunterbrechung wiedergegeben wird, um zu verhindern, dass Nutzer zu Anzeigen springen.
5. Content-Playhead-Tracker und End-of-Stream-Observer implementieren
Wenn Mid-Roll-Anzeigen wiedergegeben werden sollen, muss das IMA SDK die aktuelle Position Ihres Videoinhalts verfolgen. Um die aktuelle Position an IMA zu übergeben, erstellen Sie eine Klasse, die IMAContentPlayhead implementiert. Wenn Sie einen AVPlayer verwenden, wie in diesem Beispiel
gezeigt, stellt das IMA SDK die IMAAVPlayerContentPlayhead Klasse bereit, um die Informationen zur aktuellen
Position für Sie zu übergeben. Wenn Sie AVPlayer nicht verwenden, implementieren Sie IMAContentPlayhead in einer eigenen Klasse.
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()
}
Richten Sie einen Listener ein, um contentComplete für IMAAdsLoader aufzurufen, wenn Ihre Inhalte mit AVPlayerItemDidPlayToEndTimeNotification enden. Durch den Aufruf von contentComplete weiß das IMA SDK, wann die Wiedergabe Ihrer Inhalte beendet ist, um Post-Roll-Anzeigen auszuliefern.
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. Anzeigenladeprogramm initialisieren und Anzeigenanfrage stellen
Wenn Sie eine Reihe von Anzeigen anfordern möchten, erstellen Sie eine IMAAdsLoader-Instanz.
Dieses Ladeprogramm verarbeitet IMAAdsRequest-Objekte, die mit einer bestimmten Anzeigen-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 aber dasselbe 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. Anzeigenladeprogramm-Delegaten einrichten
Bei einem erfolgreichen Ladeereignis ruft IMAAdsLoader die Methode adsLoadedWithData des zugewiesenen Delegaten auf und übergibt eine Instanz von IMAAdsManager.
Nachdem Sie die IMAAdsManager-Instanz haben, initialisieren Sie den Anzeigenmanager, der einzelne Anzeigen basierend auf der Antwort der Anzeigen-Tag-URL lädt.
Bei nicht erfolgreichen Ladeereignissen richten Sie einen IMAAdsLoader-Delegaten ein, um Fehler zu verarbeiten, die während des Ladevorgangs auftreten. Wenn Anzeigen nicht geladen werden, muss die Medienwiedergabe ohne Anzeigen fortgesetzt werden, damit Nutzer die Medieninhalte ansehen können.
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. Anzeigenmanager-Delegaten einrichten
Schließlich benötigt der Anzeigenmanager einen eigenen Delegaten, um Ereignisse und Statusänderungen zu verwalten. IMAAdManagerDelegate enthält Methoden zum Verarbeiten von Anzeigenereignissen und -fehlern sowie Methoden zum Auslösen der Wiedergabe und Pause für Ihre Videoinhalte.
Wiedergabe starten
Die Methode didReceiveAdEvent verarbeitet alle IMAAdEvent-Ereignisse.
In diesem einfachen Beispiel wird auf das Ereignis LOADED 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 Fallback-Image für das Symbol 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, setzen Sie die Wiedergabe der Inhalte 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 Pauseereignisse auslösen
Die letzten beiden Delegatenmethoden, die Sie implementieren, lösen Wiedergabe- und Pauseereignisse für die zugrunde liegenden Videoinhalte aus, wenn sie vom IMA SDK angefordert werden. Wenn Sie die Wiedergabe und Pause auslösen, wenn sie vom IMA SDK angefordert werden, verpassen Nutzer keine Teile des Videoinhalts, wenn Anzeigen ausgeliefert 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()
}
Jetzt weißt du Bescheid. Sie fordern jetzt Anzeigen mit dem IMA SDK an und liefern sie aus. Weitere Informationen zu zusätzlichen SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.
Nächste Schritte
Wenn Sie die Werbeeinnahmen auf der tvOS-Plattform maximieren möchten, fordern Sie die Berechtigung für App-Transparenz und Tracking an, um IDFA zu verwenden.