Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedi annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA lato client, tu mantieni il controllo della riproduzione dei contenuti video, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in video player separato posizionato sopra il video player di contenuti dell'app.
Questa guida illustra come integrare l'SDK IMA in un video player semplice dell'app. Se vuoi visualizzare o seguire un campione completo integrazione, scarica BasicExample di GitHub.
Panoramica lato client IMA
L'implementazione lato client IMA prevede quattro componenti SDK principali, come mostrato in questa guida:
IMAAdDisplayContainer: Un oggetto contenitore in cui vengono visualizzati gli annunci.IMAAdsLoader: Un oggetto che richiede annunci e gestisce gli eventi provenienti dalle risposte alle richieste di annunci. Dovresti soltanto creare un'istanza per un 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, parametri aggiuntivi, come le dimensioni degli annunci.IMAAdsManager: Un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione dell'annuncio e rimane in ascolto dell'annuncio eventi attivati dall'SDK.
Prerequisiti
Prima di iniziare, è necessario quanto segue:
- Xcode 13 o versioni successive
- CocoaPods (opzione preferita), Swift Package Manager o una copia scaricata SDK IMA per iOS
1. Crea un nuovo progetto Xcode
In Xcode, crea un nuovo progetto iOS utilizzando Objective-C o Swift. Utilizza le funzionalità di BasicExample come nome del progetto.
2. Aggiungi l'SDK IMA al progetto Xcode
Installa l'SDK utilizzando CocoaPods (consigliato)
CocoaPods è un gestore delle dipendenze per i progetti Xcode ed è il modello per installare l'SDK IMA. Per ulteriori informazioni sull'installazione o l'utilizzo Consulta la documentazione di CocoaPods. Una volta Se hai 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.23.0' endDalla directory che contiene il podfile, esegui
pod install --repo-updateVerifica che l'installazione sia riuscita aprendo il BasicExample.xcworkspace e conferma che contenga due progetti: BasicExample e Pods (le dipendenze installate da CocoaPods).
Installa l'SDK utilizzando il gestore pacchetti Swift
L'SDK Interactive Media Ads supporta il pacchetto Swift Manager a partire dalla versione 3.18.4. Segui le i passaggi seguenti per importare il pacchetto Swift.
In Xcode, installa il pacchetto Swift SDK IMA accedendo a File > Aggiungi pacchetti...
Nel prompt visualizzato, cerca GitHub IMA SDK Swift Package repository:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-iosSeleziona la versione del pacchetto Swift SDK IMA che vuoi utilizzare. Per i nuovi progetti, consigliamo di utilizzare la versione principale fino alla successiva.
Quando hai finito, Xcode risolve le dipendenze dei pacchetti li scarica in background. Per maggiori dettagli su come aggiungere un pacchetto , vedi le dipendenze 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.
Mostra/nascondi istruzioni
- Da iOS pagina Download IMA, scarica ed estrai la versione più recente dell' SDK IMA per iOS.
- Apri BasicExample.xcodeproj.
- Nel riquadro a sinistra, fai clic sul nome del progetto.
- Nel riquadro centrale, fai clic su Fasi di creazione.
- Espandi la sezione Collega file binario con le librerie.
- Fai clic sull'icona Più in fondo all'elenco delle biblioteche. [+]
- Fai clic su Aggiungi altro.
- Nella directory in cui hai estratto l'SDK scaricato, seleziona GoogleInteractiveMediaAds.framework e fai clic su Apri.
- Fai clic sull'icona Più in fondo all'elenco delle biblioteche. [+] di nuovo.
- Nella colonna Stato, verifica che
GoogleInteractiveMediaAds.frameworkimpostato suRequired. - Includi il flag linker
-ObjCnelle impostazioni della build. Per ulteriori informazioni, vedi Apple QA1490.
3. Creare un video player semplice
Innanzitutto, implementa un video player di base. Inizialmente, questo player non utilizza 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. Importa l'SDK IMA
In seguito, aggiungi il framework IMA utilizzando un'istruzione di importazione sotto quella e le importazioni.
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. Implementare il tracker della testina di riproduzione dei contenuti e l'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 fa questa operazione.
Se non utilizzi AVPlayer, devi implementare IMAContentPlayhead su
per una classe.
Devi anche comunicare all'SDK quando termina la riproduzione dei contenuti in modo che possa
visualizzare annunci post-roll. Per farlo, chiama contentComplete sul
IMAAdsLoader, con 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. Inizializza il caricatore di annunci ed effettua una richiesta di annunci
Per richiedere una serie di annunci, devi creare un'istanza IMAAdsLoader.
Questo caricatore può essere utilizzato per elaborare IMAAdsRequest oggetti associati a un
specificato nell'URL del tag annuncio.
Come best practice, gestisci una sola istanza di IMAAdsLoader per l'intera
ciclo di vita della tua app. Per effettuare altre richieste di annunci, crea una nuova
IMAAdsRequest, ma riutilizza lo stesso oggetto IMAAdsLoader. Per maggiori 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. Configura un delegato del caricatore di annunci
In caso di evento di caricamento riuscito, IMAAdsLoader chiama adsLoadedWithData
del delegato assegnato, passandogli un'istanza di IMAAdsManager. Tu
può inizializzare Gestione annunci, che carica i singoli annunci, come definito
dalla risposta all'URL del tag annuncio.
Inoltre, assicurati di gestire eventuali errori che possono verificarsi durante il caricamento. e il processo di sviluppo. Se gli annunci non si caricano, assicurati che la riproduzione dei contenuti multimediali prosegua 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 per un amministratore annunci
Infine, per gestire gli eventi e le modifiche allo stato, il gestore degli annunci ha bisogno di un delegato
si tratta di una risorsa completamente
dedicata. IMAAdManagerDelegate offre metodi per gestire errori ed eventi correlati agli annunci.
nonché i metodi per attivare la riproduzione e la messa in pausa dei contenuti video.
Avvio riproduzione
Esistono molti eventi che può essere utilizzato il metodo didReceiveAdEvent,
ma per questo esempio base basta ascoltare l'evento LOADED per indicare agli annunci
per 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 anche un gestore per gli errori relativi agli annunci. Se si verifica un errore, come nell'esempio 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()
}
Attivare eventi di riproduzione e pausa
Gli ultimi due metodi di delega che devi implementare vengono usati per attivare la riproduzione mettono in pausa gli eventi sui contenuti video sottostanti, quando richiesto dall'SDK IMA. Attivare la messa in pausa e la riproduzione quando richiesto impedisce all'utente di perdere parti dei contenuti video quando vengono mostrati 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 stai richiedendo e mostrando gli annunci con l'SDK IMA. Per apprendere sulle funzioni aggiuntive dell'SDK, consulta le altre guide o su GitHub.
Passaggi successivi
Per massimizzare le entrate pubblicitarie sulla piattaforma iOS, richiedi l'autorizzazione App Transparency e Tracking per utilizzare l'IDFA.