Ten przewodnik dotyczy integracji pakietu IMA DAI SDK z aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć lub prześledzić gotową przykładową integrację, pobierz BasicExample z GitHub.
Omówienie IMA DAI
Wdrożenie IMA DAI obejmuje 3 główne komponenty pakietu SDK, które opisujemy w tym przewodniku:
IMAAdDisplayContainer: obiekt kontenera, który znajduje się nad elementem odtwarzania wideo i zawiera elementy interfejsu reklamy.IMAAdsLoader: obiekt, który żąda strumieni i obsługuje zdarzenia wywoływane przez obiekty odpowiedzi na żądanie strumienia. Należy utworzyć tylko 1 instancję obiektu ads loader, którą można wielokrotnie wykorzystywać przez cały okres działania aplikacji.IMAStreamRequest–IMAVODStreamRequestlubIMALiveStreamRequest: obiekt, który definiuje żądanie strumienia. Żądania strumieni mogą dotyczyć filmów na żądanie lub transmisji na żywo. Żądania transmisji na żywo określają klucz zasobu, a żądania VOD – identyfikator CMS i identyfikator filmu. Oba typy żądań mogą opcjonalnie zawierać klucz interfejsu API potrzebny do uzyskania dostępu do określonych strumieni oraz kod sieci Google Ad Managera, który umożliwia pakietowi IMA SDK obsługę identyfikatorów reklam zgodnie z ustawieniami Google Ad Managera.IMAStreamManager: obiekt, który obsługuje strumienie dynamicznego wstawiania reklam i interakcje z backendem DAI. Menedżer strumienia obsługuje też pingi śledzące i przekazuje wydawcy zdarzenia strumienia i reklamy.
Wymagania wstępne
Zanim zaczniesz, musisz mieć:
- Xcode 13 lub nowszy,
- Metoda instalacji pakietu IMA SDK:
- Swift Package Manager (preferowany)
- pobrana kopia pakietu IMA SDK na tvOS,
Tworzenie nowego projektu Xcode
W Xcode utwórz nowy projekt tvOS przy użyciu Objective-C. Jako nazwy projektu użyj BasicExample.
Dodawanie pakietu IMA DAI SDK do projektu w Xcode
Aby zainstalować pakiet IMA SDK, wybierz preferowaną metodę.
Zalecane: zainstaluj pakiet SDK za pomocą narzędzia Swift Package Manager
Pakiet Interactive Media Ads SDK obsługuje Swift Package Manager od wersji 4.8.2. Aby zaimportować pakiet Swift, wykonaj te czynności.
W Xcode zainstaluj pakiet GoogleInteractiveMediaAds Swift, klikając File > Add Packages (Plik > Dodaj pakiety).
W wyświetlonym oknie wyszukaj repozytorium GitHub pakietu GoogleInteractiveMediaAds Swift:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosWybierz wersję pakietu GoogleInteractiveMediaAds Swift, której chcesz używać. W przypadku nowych projektów zalecamy używanie opcji Up to Next Major Version (Do następnej wersji głównej).
Gdy skończysz, Xcode przetworzy zależności pakietu i pobierze je w tle. Więcej informacji o dodawaniu zależności pakietów znajdziesz w artykule Apple.
Ręczne pobieranie i instalowanie pakietu SDK
Jeśli nie chcesz używać menedżera pakietów Swift, pobierz i ręcznie dodaj pakiet IMA SDK do projektu.
Importowanie pakietu IMA SDK
Dodaj platformę IMA za pomocą instrukcji importu:
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
Tworzenie odtwarzacza i integrowanie go z pakietem IMA SDK
Poniższy przykład inicjuje pakiet IMA SDK:
Objective-C
// Live stream asset key, VOD content source and video IDs, and backup content URL.
static NSString *const kAssetKey = @"c-rArva4ShKVIAkNfy6HUQ";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
static NSString *const kBackupStreamURLString =
@"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/"
@"master.m3u8";
static const StreamType kDefaultStreamType = StreamTypeLive;
@interface ViewController () <IMAAdsLoaderDelegate,
IMAStreamManagerDelegate,
AVPlayerViewControllerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) id<IMAVideoDisplay> videoDisplay;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
self.streamType = kDefaultStreamType;
[self setupAdsLoader];
[self setupPlayer];
[self setupAdContainer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestStream];
}
- (void)setupPlayer {
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach video player to view hierarchy.
[self addChildViewController:self.playerViewController];
[self.view addSubview:self.playerViewController.view];
self.playerViewController.view.frame = self.view.bounds;
[self.playerViewController didMoveToParentViewController:self];
}
Swift
class ViewController:
UIViewController,
IMAAdsLoaderDelegate,
IMAStreamManagerDelegate,
AVPlayerViewControllerDelegate
{
// Live stream asset key, VOD content source and video IDs, Google Ad Manager network code, and
// backup content URL.
static let assetKey = "c-rArva4ShKVIAkNfy6HUQ"
static let contentSourceID = "2548831"
static let videoID = "tears-of-steel"
static let networkCode = "21775744923"
static let backupStreamURLString =
"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/master.m3u8"
var adsLoader: IMAAdsLoader?
var videoDisplay: IMAAVPlayerVideoDisplay!
var adDisplayContainer: IMAAdDisplayContainer?
var adContainerView: UIView?
private var streamManager: IMAStreamManager?
private var contentPlayhead: IMAAVPlayerContentPlayhead?
private var playerViewController: AVPlayerViewController!
private var userSeekTime = 0.0
private var adBreakActive = false
private enum StreamType {
case live
/// Video on demand.
case vod
}
/// Set the stream type here.
private let currentStreamType: StreamType = .live
deinit {
NotificationCenter.default.removeObserver(self)
}
override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor.black
setupAdsLoader()
setupPlayer()
setupAdContainer()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
requestStream()
}
func setupPlayer() {
let player = AVPlayer()
let playerViewController = AVPlayerViewController()
playerViewController.delegate = self
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)
self.addChild(playerViewController)
playerViewController.view.frame = self.view.bounds
self.view.insertSubview(playerViewController.view, at: 0)
playerViewController.didMove(toParent: self)
self.playerViewController = playerViewController
}
W viewDidLoad() setupAdsLoader() tworzy IMAAdsLoader, setupPlayer() tworzy AVPlayerViewController, a setupAdContainer() przygotowuje UIView do wyświetlania reklam. Gdy widok stanie się widoczny, viewDidAppear() wywołuje requestStream(), aby poprosić o transmisję DAI.
Aby zdefiniować parametry żądania strumienia, w tym przykładzie użyto stałych, takich jak asset key w przypadku transmisji na żywo lub content source ID i video ID w przypadku strumieni VOD. W przykładzie użyto też tych komponentów do zarządzania pakietem IMA SDK:
adsLoader: obsługuje żądania strumienia wysyłane do Google Ad Managera. Zalecamy używanie jednej instancji przez cały cykl życia aplikacji.videoDisplay: implementacjaIMAVideoDisplay, która umożliwia IMA kontrolowanie odtwarzania filmów i śledzenie zdarzeń odtwarzania za pomocą AVPlayer.adDisplayContainer: zarządza widokiem używanym do renderowania elementów interfejsu reklamy i obsługi zaznaczenia interfejsu podczas przerw na reklamę.streamManager: zarządza odtwarzaniem połączonego strumienia reklamy i treści oraz wysyła zdarzenia cyklu życia reklamy za pomocą swojego delegata.playerViewController: odtwarzacz tvOS używany do wyświetlania strumienia wideo zarządzanego przez pakiet IMA SDK.adBreakActive: flaga logiczna, która wskazuje, czy przerwa na reklamę jest odtwarzana. Służy do zapobiegania przewijaniu reklam i do zarządzania fokusem interfejsu.
Implementacja IMAAdsLoader
Następnie utwórz instancję IMAAdsLoader i dołącz widok kontenera reklamy do hierarchii widoków.
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)setupAdContainer {
// Attach the ad container to the view hierarchy on top of the player.
self.adContainerView = [[UIView alloc] init];
[self.view addSubview:self.adContainerView];
self.adContainerView.frame = self.view.bounds;
// Keep hidden initially, until an ad break.
self.adContainerView.hidden = YES;
}
Swift
func setupAdsLoader() {
let adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self
self.adsLoader = adsLoader
}
func setupAdContainer() {
// Attach the ad container to the view hierarchy on top of the player.
let adContainerView = UIView()
self.view.addSubview(adContainerView)
adContainerView.frame = self.view.bounds
// Keep hidden initially, until an ad break.
adContainerView.isHidden = true
self.adContainerView = adContainerView
}
Wysyłanie żądania strumienia
Utwórz kilka stałych, które będą przechowywać informacje o strumieniu, a następnie zaimplementuj funkcję żądania strumienia, aby wysłać żądanie.
Objective-C
- (void)requestStream {
self.videoDisplay =
[[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView
viewController:self];
// Use the streamType property to determine which request to create.
switch (self.streamType) {
case StreamTypeLive: {
IMALiveStreamRequest *request =
[[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
networkCode:kNetworkCode
adDisplayContainer:self.adDisplayContainer
videoDisplay:self.videoDisplay
userContext:nil];
NSLog(@"IMA: Requesting Live Stream with Asset Key: %@.", kAssetKey);
request.useHLSInterstitials = YES;
[self.adsLoader requestStreamWithRequest:request];
break;
}
case StreamTypeVOD: {
IMAVODStreamRequest *request =
[[IMAVODStreamRequest alloc] initWithContentSourceID:kContentSourceID
videoID:kVideoID
networkCode:kNetworkCode
adDisplayContainer:self.adDisplayContainer
videoDisplay:self.videoDisplay
userContext:nil];
NSLog(@"IMA: Requesting VOD Stream with Video ID: %@.", kVideoID);
[self.adsLoader requestStreamWithRequest:request];
break;
}
}
}
Swift
func requestStream() {
guard let playerViewController = self.playerViewController else { return }
guard let adContainerView = self.adContainerView else { return }
guard let adsLoader = self.adsLoader else { return }
self.videoDisplay = IMAAVPlayerVideoDisplay(avPlayer: playerViewController.player!)
let adDisplayContainer = IMAAdDisplayContainer(
adContainer: adContainerView, viewController: self)
self.adDisplayContainer = adDisplayContainer
switch self.currentStreamType {
case .live:
// Create a live stream request.
let request = IMALiveStreamRequest(
assetKey: ViewController.assetKey,
networkCode: ViewController.networkCode,
adDisplayContainer: adDisplayContainer,
videoDisplay: self.videoDisplay,
pictureInPictureProxy: nil,
userContext: nil)
print("IMA: Requesting Live Stream with asset key \(ViewController.assetKey)")
request.useHLSInterstitials = true
adsLoader.requestStream(with: request)
case .vod:
// Create a VOD stream request.
let request = IMAVODStreamRequest(
contentSourceID: ViewController.contentSourceID,
videoID: ViewController.videoID,
networkCode: ViewController.networkCode,
adDisplayContainer: adDisplayContainer,
videoDisplay: self.videoDisplay,
pictureInPictureProxy: nil,
userContext: nil)
print(
"IMA: Requesting VOD Stream with content source ID \(ViewController.contentSourceID) and "
+ "video ID \(ViewController.videoID)")
adsLoader.requestStream(with: request)
}
}
Obsługa zdarzeń strumienia
IMAAdsLoader i IMAStreamManager wywołują zdarzenia, które obsługują inicjowanie, błędy i zmiany stanu strumienia. Te zdarzenia są wywoływane przez protokoły IMAAdsLoaderDelegate i IMAStreamManagerDelegate. Nasłuchuj zdarzenia wczytania reklam i zainicjuj transmisję. Jeśli nie uda się wczytać reklamy, odtwórz strumień zapasowy.
Objective-C
- (void)playBackupStream {
NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
[self.videoDisplay loadStream:backupStreamURL withSubtitles:@[]];
[self.videoDisplay play];
[self startMediaSession];
}
- (void)startMediaSession {
[[AVAudioSession sharedInstance] setActive:YES error:nil];
[[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback error:nil];
}
#pragma mark - IMAAdsLoaderDelegate
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Initialize and listen to stream manager's events.
self.streamManager = adsLoadedData.streamManager;
self.streamManager.delegate = self;
[self.streamManager initializeWithAdsRenderingSettings:nil];
NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Fall back to playing the backup stream.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self playBackupStream];
}
Swift
@objc func contentDidFinishPlaying(_ notification: Notification) {
guard let adsLoader = self.adsLoader else { return }
adsLoader.contentComplete()
}
func startMediaSession() {
try? AVAudioSession.sharedInstance().setActive(true, options: [])
try? AVAudioSession.sharedInstance().setCategory(.playback)
}
// MARK: - IMAAdsLoaderDelegate
func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
let streamManager = adsLoadedData.streamManager!
streamManager.delegate = self
streamManager.initialize(with: nil)
self.streamManager = streamManager
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("Error loading ads: \(adErrorData.adError.message)")
let streamUrl = URL(string: ViewController.backupStreamURLString)
self.videoDisplay.loadStream(streamUrl!, withSubtitles: [])
self.videoDisplay.play()
playerViewController.player?.play()
}
Obsługa zdarzeń logowania i błędów
Delegat menedżera strumienia może obsługiwać kilka zdarzeń, ale w przypadku podstawowych implementacji najważniejsze zastosowania to rejestrowanie zdarzeń, zapobieganie przewijaniu podczas odtwarzania reklam i obsługa błędów.
Objective-C
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
NSLog(@"StreamManager event (%@).", event.typeString);
switch (event.type) {
case kIMAAdEvent_STREAM_STARTED: {
[self startMediaSession];
break;
}
case kIMAAdEvent_STARTED: {
// Log extended data.
NSString *extendedAdPodInfo = [[NSString alloc]
initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
@"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];
NSLog(@"%@", extendedAdPodInfo);
break;
}
case kIMAAdEvent_AD_BREAK_STARTED: {
self.adContainerView.hidden = NO;
// Trigger an update to send focus to the ad display container.
self.adBreakActive = YES;
[self setNeedsFocusUpdate];
break;
}
case kIMAAdEvent_AD_BREAK_ENDED: {
self.adContainerView.hidden = YES;
// Trigger an update to send focus to the content player.
self.adBreakActive = NO;
[self setNeedsFocusUpdate];
break;
}
case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
// Resume playback after the user has closed the dialog.
[self.videoDisplay play];
break;
}
default:
break;
}
}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
// Fall back to playing the backup stream.
NSLog(@"StreamManager error: %@", error.message);
[self playBackupStream];
}
Swift
// MARK: - IMAStreamManagerDelegate
func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
print("StreamManager event \(event.typeString).")
switch event.type {
case IMAAdEventType.STREAM_STARTED:
self.startMediaSession()
case IMAAdEventType.STARTED:
// Log extended data.
if let ad = event.ad {
let extendedAdPodInfo = String(
format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
+ "description: %@, contentType:%@, pod index: %zd, "
+ "time offset: %lf, max duration: %lf.",
ad.adPodInfo.adPosition,
ad.adPodInfo.totalAds,
ad.adPodInfo.isBumper ? "YES" : "NO",
ad.adTitle,
ad.adDescription,
ad.contentType,
ad.adPodInfo.podIndex,
ad.adPodInfo.timeOffset,
ad.adPodInfo.maxDuration)
print("\(extendedAdPodInfo)")
}
break
case IMAAdEventType.AD_BREAK_STARTED:
if let adContainerView = self.adContainerView {
adContainerView.isHidden = false
}
// Trigger an update to send focus to the ad display container.
adBreakActive = true
setNeedsFocusUpdate()
break
case IMAAdEventType.AD_BREAK_ENDED:
if let adContainerView = self.adContainerView {
adContainerView.isHidden = true
}
// Trigger an update to send focus to the content player.
adBreakActive = false
setNeedsFocusUpdate()
break
case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
// Resume playback after the user has closed the dialog.
self.videoDisplay.play()
break
default:
break
}
}
func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
print("StreamManager error: \(error.message ?? "Unknown Error")")
}
To wszystko. Teraz wysyłasz żądania reklam i wyświetlasz je za pomocą pakietu IMA DAI SDK. Aby dowiedzieć się więcej o bardziej zaawansowanych funkcjach pakietu SDK, zapoznaj się z innymi przewodnikami lub przykładami na GitHubie.