Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA DAI, le app inviano una richiesta di streaming per gli annunci e i video di contenuti, sia VOD che dal vivo. L'SDK restituisce quindi un stream video combinato, in modo da non dover gestire il passaggio tra annunci e video di contenuti all'interno della tua app.
Seleziona la soluzione DAI che ti interessa
DAI con servizio completo
Questa guida illustra come integrare l'SDK IMA DAI in una semplice app di video player. Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica BasicExample da GitHub.
Panoramica dell'inserimento di annunci dinamici in IMA
L'implementazione di IMA DAI prevede tre componenti principali dell'SDK, come mostrato in questa guida:
IMAAdDisplayContainer
: un oggetto contenitore che si trova sopra l'elemento di riproduzione video e contiene gli elementi dell'interfaccia utente dell'annuncio.IMAAdsLoader
: un oggetto che richiede stream e gestisce gli eventi attivati dagli oggetti di risposta alla richiesta di stream. Devi creare un'istanza di un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.IMAStreamRequest
: un valoreIMAVODStreamRequest
oIMALiveStreamRequest
. Un oggetto che definisce una richiesta di stream. Le richieste di stream possono riguardare video on demand o live streaming. Le richieste specificano un ID contenuto, nonché una chiave API o un token di autenticazione e altri parametri.IMAStreamManager
: un oggetto che gestisce gli stream di inserimento di annunci dinamici e le interazioni con il backend DAI. Il gestore dello stream gestisce anche i ping di monitoraggio e inoltra gli eventi relativi allo stream e agli annunci al publisher.
Prerequisiti
Prima di iniziare, devi disporre di quanto segue:
- Xcode 13 o versioni successive
- CocoaPods (opzione preferita), Swift Package Manager o una copia scaricata dell'SDK IMA DAI per tvOS
Creare un nuovo progetto Xcode
In Xcode, crea un nuovo progetto tvOS utilizzando Objective-C. Utilizza BasicExample come nome del progetto.
Aggiungi l'SDK IMA DAI al progetto Xcode
Utilizza uno di questi tre metodi per installare l'SDK IMA DAI.
Installa l'SDK utilizzando CocoaPods (opzione preferita)
CocoaPods è un gestore delle dipendenze per i progetti Xcode ed è il metodo consigliato per installare l'SDK IMA DAI. Per ulteriori informazioni sull'installazione o sull'utilizzo di CocoaPods, consulta la documentazione di CocoaPods. Dopo aver installato CocoaPods, segui le istruzioni riportate di seguito per installare l'SDK IMA DAI:
Nella stessa directory del file BasicExample.xcodeproj, crea un file di testo chiamato Podfile e aggiungi la seguente configurazione:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '14' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0' end
Dalla directory che contiene il file Podfile, esegui:
pod install --repo-update`
Verifica che l'installazione sia andata a buon fine aprendo il file BasicExample.xcworkspace e verificando che contenga due progetti: BasicExample e Pods (le dipendenze installate da CocoaPods).
Installa l'SDK utilizzando Swift Package Manager
L'SDK Interactive Media Ads supporta Swift Package Manager a partire dalla versione 4.8.2. Segui questi passaggi per importare il pacchetto Swift.
In Xcode, installa il pacchetto Swift GoogleInteractiveMediaAds andando a File > Aggiungi pacchetti.
Nella richiesta visualizzata, cerca il repository GitHub del pacchetto Swift GoogleInteractiveMediaAds:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
Seleziona la versione del pacchetto Swift GoogleInteractiveMediaAds che vuoi utilizzare. Per i nuovi progetti, consigliamo di utilizzare l'opzione Fino alla versione principale successiva.
Al termine, Xcode risolve le dipendenze del pacchetto e le scarica in background. Per maggiori dettagli su come aggiungere le dipendenze del pacchetto, consulta l'articolo di Apple.
Download e installazione manuale dell'SDK
Se non vuoi utilizzare Swift Package Manager o CocoaPods, puoi scaricare l'SDK IMA DAI e aggiungerlo manualmente al tuo progetto.
Creare un semplice video player
Innanzitutto, implementa un video player di base. Inizialmente, questo player non utilizza l'SDK IMA DAI né contiene alcun metodo per attivare la riproduzione.
ViewController.m
#import "ViewController.h"
#import <AVKit/AVKit.h>
@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach the video player to the view hierarchy.
[self addChildViewController:self.playerViewController];
self.playerViewController.view.frame = self.view.bounds;
[self.view addSubview:self.playerViewController.view];
[self.playerViewController didMoveToParentViewController:self];
}
@end
Importa l'SDK e aggiungi stub per l'interazione con IMA
Dopo aver aggiunto l'SDK IMA DAI al progetto, importa l'SDK e aggiungi gli stub per i punti di interazione principali di IMA.
ViewController.m
#import "ViewController.h"
#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach the video player to the view hierarchy.
[self addChildViewController:self.playerViewController];
self.playerViewController.view.frame = self.view.bounds;
[self.view addSubview:self.playerViewController.view];
[self.playerViewController didMoveToParentViewController:self];
[self attachAdContainer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestStream];
}
- (void)setupAdsLoader {}
- (void)attachAdContainer {}
- (void)requestStream {}
@end
Implementa IMAAdsLoader
Poi, esegui l'inizializzazione di IMAAdsLoader
e associa la visualizzazione del contenitore degli annunci alla gerarchia delle visualizzazioni.
ViewController.m
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)attachAdContainer {
self.adContainerView = [[UIView alloc] init];
[self.view addSubview:self.adContainerView];
self.adContainerView.frame = self.view.bounds;
}
Inviare una richiesta di streaming
Crea alcune costanti per memorizzare le informazioni sullo stream e poi implementa la funzione di richiesta dello stream per effettuare la richiesta.
ViewController.m
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
@interface ViewController ()
...
- (void)requestStream {
IMAAVPlayerVideoDisplay *videoDisplay =
[[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
IMAAdDisplayContainer *adDisplayContainer =
[[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
adDisplayContainer:adDisplayContainer
videoDisplay:videoDisplay];
// VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
// to switch from a livestream to a VOD stream.
// IMAVODStreamRequest *request =
// [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
// videoId:kVideoID
// adDisplayContainer:adDisplayContainer
// videoDisplay:videoDisplay];
[self.adsLoader requestStreamWithRequest:request];
}
Gestire gli eventi stream
IMAAdsLoader
e IMAStreamManager
attivano eventi che vengono utilizzati per gestire l'inizializzazione, gli errori e le modifiche dello stato dello stream. Questi eventi vengono attivati tramite i protocolli IMAAdsLoaderDelegate
e IMAStreamManagerDelegate
. Ascolta un evento di caricamento degli annunci e inizializza lo stream. Se un annuncio non viene caricato, riproduci
uno stream di backup.
ViewController.m
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
@"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
...
[self.adsLoader requestStreamWithRequest:request];
}
- (void)playBackupStream {
NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
[self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
[self.playerViewController.player play];
}
#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];
}
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}
- (void)streamManager:(IMAStreamManager *)streamManager
adDidProgressToTime:(NSTimeInterval)time
adDuration:(NSTimeInterval)adDuration
adPosition:(NSInteger)adPosition
totalAds:(NSInteger)totalAds
adBreakDuration:(NSTimeInterval)adBreakDuration {}
@end
Gestire gli eventi di logging e di errore
Esistono diversi eventi che possono essere gestiti dal delegato dello stream manager, ma per le implementazioni di base, gli utilizzi più importanti sono eseguire il logging degli eventi, impedire le azioni di ricerca durante la riproduzione degli annunci e gestire gli errori.
ViewController.m
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
NSLog(@"StreamManager event (%@).", event.typeString);
switch (event.type) {
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: {
// Prevent user seek through when an ad starts and show the ad controls.
self.adContainerView.hidden = NO;
break;
}
case kIMAAdEvent_AD_BREAK_ENDED: {
// Allow user seek through after an ad ends and hide the ad controls.
self.adContainerView.hidden = YES;
break;
}
default:
break;
}
}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
// Fall back to playing the backup stream.
NSLog(@"StreamManager error: %@", error.message);
[self playBackupStream];
}
@end
È tutto. Ora richiedi e visualizzi gli annunci con l'SDK IMA DAI. Per scoprire di più sulle funzionalità dell'SDK più avanzate, consulta le altre guide o i sample su GitHub.