Gli SDK IMA semplificano l'integrazione di annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK lato client IMA puoi mantenere il controllo della riproduzione dei video dei contenuti, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in un video player separato posizionato sopra il video player dei contenuti dell'app.
Questa guida illustra come integrare l'SDK IMA in una semplice app video player. Se desideri visualizzare o seguire un'integrazione di esempio completata, scarica BasicExample da GitHub.
Panoramica lato client IMA
L'implementazione lato client IMA prevede l'utilizzo di quattro componenti principali dell'SDK, illustrati in questa guida:
IMAAdDisplayContainer
: un oggetto contenitore in cui viene eseguito il rendering degli annunci.IMAAdsLoader
: un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. Devi ottimizzare un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.IMAAdsRequest
: un oggetto che definisce una richiesta di annunci. Le richieste di annunci specificano l'URL del tag annuncio VAST e parametri aggiuntivi, come le dimensioni dell'annuncio.IMAAdsManager
: un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione dell'annuncio e ascolta gli eventi annunci attivati dall'SDK.
Prerequisiti
Prima di iniziare, devi disporre di:
- Xcode 13 o versioni successive
- CocoaPods (opzione preferita), Swift Package Manager o una copia scaricata dell'SDK IMA per iOS
1. Crea un nuovo progetto Xcode
In Xcode, crea un nuovo progetto iOS utilizzando Objective-C o Swift. Utilizza BasicExample come nome del progetto.
2. Aggiungere l'SDK IMA al progetto Xcode
Installa l'SDK utilizzando CocoaPods (consigliato)
CocoaPods è un gestore delle dipendenze per i progetti Xcode ed è il metodo consigliato per installare l'SDK IMA. Per ulteriori informazioni sull'installazione o sull'utilizzo di CocoaPods, consulta la documentazione di CocoaPods. Dopo aver installato CocoaPods, segui queste istruzioni per installare l'SDK IMA:
Nella stessa directory del file BasicExample.xcodeproj, crea un file di testo denominato Podfile e aggiungi la seguente configurazione:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '14' target "BasicExample" do pod 'GoogleAds-IMA-iOS-SDK', '~> 3.22.1' end
Dalla directory che contiene il podfile, esegui
pod install --repo-update
Verifica che l'installazione sia riuscita aprendo il file BasicExample.xcworkspace e confermando che contiene 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 3.18.4. Segui i passaggi riportati di seguito per importare il pacchetto Swift.
In Xcode, installa l'SDK IMA Swift Package selezionando File > Aggiungi pacchetti....
Nel prompt visualizzato, cerca il repository GitHub di IMA SDK Swift Package:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
Seleziona la versione del pacchetto Swift dell'SDK IMA che vuoi utilizzare. Per i nuovi progetti, consigliamo di utilizzare la versione principale successiva.
Al termine, Xcode risolve le dipendenze dei pacchetti e le scarica in background. Per ulteriori dettagli su come aggiungere dipendenze dei pacchetti, consulta l'articolo di Apple.
Scarica e installa manualmente l'SDK
Se non vuoi utilizzare Swift Package Manager o CocoaPods, puoi scaricare l'SDK IMA e aggiungerlo manualmente al tuo progetto.
3. Creare un video player semplice
Innanzitutto, implementa un video player di base. Inizialmente, questo player non utilizza l'SDK IMA e non contiene ancora alcun metodo per attivare la riproduzione.
ViewController.m
Objective-C
#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
Swift
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. Importare l'SDK IMA
Aggiungi quindi il framework IMA utilizzando un'istruzione di importazione sotto le importazioni esistenti.
ViewController.m
Objective-C
#import "ViewController.h" #import <AVKit/AVKit.h> #import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h> NSString *const kContentURLString = @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
Swift
import AVFoundation import GoogleInteractiveMediaAds import UIKit class ViewController: UIViewController { static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
5. Implementazione del tracker della testina di riproduzione dei contenuti e dell'osservatore di fine streaming
Per riprodurre gli annunci mid-roll, l'SDK IMA deve monitorare la posizione corrente
dei tuoi contenuti video. Per farlo, crea una classe che implementi
IMAContentPlayhead
. Se utilizzi AVPlayer
, come mostrato in questo esempio,
l'SDK fornisce la classe IMAAVPlayerContentPlayhead
, che esegue questa operazione per te.
Se non utilizzi AVPlayer
, dovrai implementare IMAContentPlayhead
in una tua classe.
Devi inoltre comunicare all'SDK quando termina la riproduzione dei contenuti in modo che possa visualizzare gli annunci post-roll. A tale scopo, chiama contentComplete
sul
IMAAdsLoader
utilizzando AVPlayerItemDidPlayToEndTimeNotification
.
ViewController.m
Objective-C
... @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
Swift
... 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. Inizializzare il caricatore di annunci ed effettuare una richiesta di annunci
Per richiedere un insieme di annunci, devi creare un'istanza IMAAdsLoader
.
Questo caricatore può essere utilizzato per elaborare IMAAdsRequest
oggetti associati a un
URL di tag annuncio specificato.
Come best practice, gestisci una sola istanza di IMAAdsLoader
per l'intero ciclo di vita della tua app. Per effettuare richieste di annunci aggiuntive, crea un nuovo oggetto IMAAdsRequest
, ma riutilizza lo stesso IMAAdsLoader
. Per ulteriori informazioni, consulta le Domande frequenti sull'SDK IMA.
ViewController.m
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&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
Swift
... 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 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) } @objc func contentDidFinishPlaying(_ notification: Notification) { adsLoader.contentComplete() } }
7. Configurare un delegato per il caricamento degli annunci
In caso di evento di caricamento riuscito, IMAAdsLoader
chiama il metodo adsLoadedWithData
del delegato assegnato, passando un'istanza di IMAAdsManager
. Puoi quindi inizializzare gestore annunci, che carica i singoli annunci, come definito dalla risposta all'URL del tag annuncio.
Inoltre, assicurati di gestire eventuali errori che potrebbero verificarsi durante il processo di caricamento. Se gli annunci non vengono caricati, assicurati che la riproduzione dei contenuti multimediali continui, senza annunci, in modo da non interferire con l'esperienza dell'utente.
ViewController.m
Objective-C
... @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
Swift
... 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. Impostare un delegato di gestione degli annunci
Infine, per gestire eventi e modifiche dello stato, il gestore degli annunci ha bisogno di un proprio delegato. L'IMAAdManagerDelegate
offre metodi per gestire gli eventi e gli errori relativi agli annunci,
nonché metodi per attivare la riproduzione e la messa in pausa dei contenuti video.
Avvio della riproduzione in corso...
Il metodo didReceiveAdEvent
può essere utilizzato per gestire molti eventi, ma per questo esempio di base è sufficiente rimanere in ascolto dell'evento LOADED
per indicare al gestore degli annunci di avviare la riproduzione di contenuti e annunci.
ViewController.m
Objective-C
@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]; } } ...
Swift
... 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() } } ...
Gestione degli errori
Aggiungi un gestore anche per gli errori degli annunci. Se si verifica un errore, come nel passaggio precedente, riprendi la riproduzione dei contenuti.
ViewController.m
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]; } @end
Swift
... func adsManager(_ adsManager: IMAAdsManager!, didReceive error: IMAAdError!) { // Fall back to playing content print("AdsManager error: " + error.message) showContentPlayer() playerViewController.player?.play() }
Attivazione degli eventi di riproduzione e pausa
Gli ultimi due metodi di delega da implementare vengono utilizzati per attivare gli eventi di riproduzione e pausa sui contenuti video sottostanti, quando richiesto dall'SDK IMA. L'attivazione della messa in pausa e della riproduzione quando richiesto impedisce all'utente di perdere parti dei contenuti video quando vengono visualizzati gli annunci.
ViewController.m
Objective-C
... - (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
Swift
... 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() } }
È tutto. Ora richiedi e visualizzi gli annunci con l'SDK IMA. Per scoprire di più sulle funzionalità aggiuntive dell'SDK, consulta le altre guide o gli esempi su GitHub.
Passaggi successivi
Per massimizzare le entrate pubblicitarie sulla piattaforma iOS, richiedi l'autorizzazione per la trasparenza delle app e il monitoraggio per l'utilizzo dell'IDFA.