Los SDK de IMA facilitan la integración de anuncios multimedia en sus sitios web y aplicaciones. Los SDK de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administra la reproducción de anuncios en tus apps. Con los SDK de IMA del cliente, tú mantienes el control de la reproducción de videos de contenido, mientras que el SDK controla la reproducción de anuncios. Los anuncios se reproducen en un un reproductor de video separado ubicado en la parte superior del reproductor de video de contenido de la app.
En esta guía, se muestra cómo integrar el SDK de IMA en un reproductor de video simple . Si quieres ver o seguir una muestra completa integración, descarga el BasicExample de GitHub.
Descripción general de IMA del cliente
La implementación de IMA del lado del cliente implica cuatro componentes principales del SDK, los cuales se se demuestra en esta guía:
IMAAdDisplayContainer
Es un objeto contenedor en el que se renderizan los anuncios.IMAAdsLoader
Es un objeto que solicita anuncios y controla eventos de respuestas a solicitudes de anuncios. Solo debes crear una instancia de un cargador de anuncios, que puede reutilizarse durante el ciclo de vida de la aplicación.IMAAdsRequest
Un objeto que define una solicitud de anuncios. Las solicitudes de anuncios especifican la URL de la etiqueta de anuncio de VAST, así como parámetros adicionales, como las dimensiones del anuncio.IMAAdsManager
Un objeto que contiene la respuesta a la solicitud de anuncios, controla la reproducción y escucha el anuncio eventos que activa el SDK.
Requisitos previos
Antes de comenzar, necesitas lo siguiente:
- Xcode 13 o una versión posterior
- CocoaPods (opción preferida), Swift Package Manager o un copia descargada de la SDK de IMA para iOS
1. Crea un nuevo proyecto de Xcode
En Xcode, crea un proyecto de iOS nuevo con Objective-C o Swift. Usa BasicExample como nombre del proyecto
2. Agrega el SDK de IMA al proyecto Xcode
Instala el SDK con CocoaPods (recomendado)
CocoaPods es un administrador de dependencias para proyectos de Xcode y es el para instalar el SDK de IMA. Para obtener más información sobre la instalación o el uso CocoaPods, consulta la documentación de CocoaPods. Una vez que si tienes CocoaPods instalado, sigue estas instrucciones para instalar el SDK de IMA:
En el mismo directorio en que está el archivo BasicExample.xcodeproj, crea un texto llamado Podfile y agrega la siguiente configuración:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '14' target "BasicExample" do pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0' end
Desde el directorio que contiene el Podfile, ejecuta
pod install --repo-update
.Verifica que la instalación se haya realizado correctamente. Para ello, abre la BasicExample.xcworkspace y de la confirmación de que contiene dos proyectos: BasicExample y Pods (las dependencias instaladas por CocoaPods).
Instala el SDK con Swift Package Manager
El SDK de anuncios multimedia interactivos admite Swift Package Manager a partir de la versión 3.18.4. Sigue el para importar el paquete de Swift.
Para instalar el paquete de Swift del SDK de IMA, en Xcode, navega a Archivo > Add Packages...
En el mensaje que aparece, busca el paquete de Swift del SDK de IMA en GitHub siguiente:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
Selecciona la versión del paquete de Swift del SDK de IMA que quieres usar. Para proyectos nuevos, recomendamos usar Hasta la siguiente versión principal.
Cuando finalizas, Xcode resuelve las dependencias de tus paquetes y y los descarga en segundo plano. Más información para agregar paquetes las dependencias, consulta Artículo de Apple.
Descarga e instala el SDK de forma manual
Si no quieres usar Swift Package Manager o CocoaPods, puedes descargar el SDK de IMA y agregarlo a tu proyecto de forma manual.
3. Cómo crear un reproductor de video simple
Primero, implementa un reproductor de video básico. Inicialmente, este jugador no usa el SDK de IMA y todavía no contiene ningún método para activar la reproducción.
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 el SDK de IMA
A continuación, agregue el marco de trabajo de IMA mediante una sentencia de importación debajo de la existente .
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. Implementa un rastreador de cabezas de reproducción de contenido y un observador de final de transmisión
Para reproducir anuncios durante el video, el SDK de IMA debe hacer un seguimiento de la posición actual.
del contenido de video. Para hacerlo, crea una clase que implemente
IMAContentPlayhead
Si usas un objeto AVPlayer
, como se muestra en este ejemplo,
el SDK proporciona la clase IMAAVPlayerContentPlayhead
, que lo hace por ti.
Si no usas AVPlayer
, deberás implementar IMAContentPlayhead
en
una clase propia.
También debes informar al SDK cuando se termine de reproducir el contenido para que pueda
mostrar anuncios al final del video. Para ello, se debe llamar a contentComplete
en el
IMAAdsLoader
, usando 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. Cómo inicializar el cargador de anuncios y realizar una solicitud de anuncios
Para solicitar un conjunto de anuncios, debes crear una instancia de IMAAdsLoader
.
Este cargador se puede usar para procesar objetos IMAAdsRequest
asociados con un
la URL de la etiqueta de anuncio especificada.
Como práctica recomendada, solo se debe mantener una instancia de IMAAdsLoader
para toda la instancia.
ciclo de vida de tu app. Para realizar solicitudes de anuncios adicionales, crea un nuevo
IMAAdsRequest
, pero volverá a usar el mismo IMAAdsLoader
. Para ver más
consulte las Preguntas frecuentes sobre el SDK de 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 delegado del cargador de anuncios
En un evento de carga exitoso, IMAAdsLoader
llama a adsLoadedWithData
.
de su delegado asignado y le pasa una instancia de IMAAdsManager
. Tú
Luego, puede inicializar el administrador de anuncios, que carga los anuncios individuales, como se definió.
por la respuesta a la URL de la etiqueta de anuncio.
Además, asegúrate de solucionar cualquier error que pueda ocurrir durante el proceso el proceso de administración de recursos. Si los anuncios no se cargan, asegúrate de que la reproducción del contenido multimedia continúe, sin para no interferir con la experiencia del usuario.
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. Configura un delegado de Google Ads Manager
Por último, para administrar eventos y cambios de estado, el administrador de anuncios necesita un delegado del
por sí solos. IMAAdManagerDelegate
tiene métodos para controlar errores y eventos de anuncios.
así como métodos para activar la reproducción y la pausa en el contenido de video.
Iniciando la reproducción
Hay muchos eventos que se pueden controlar con el método didReceiveAdEvent
.
pero, en este ejemplo básico, solo escucha el evento LOADED
para indicarles a los anuncios
para iniciar la reproducción de contenido y anuncios.
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() } } ...
Maneja los errores
También agrega un controlador para los errores de los anuncios. Si se produce un error, como en el evento anterior reanuda la reproducción de contenido.
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() }
Cómo activar eventos de reproducción y pausa
Los últimos dos métodos delegados que debes implementar se usan para activar el juego y eventos de pausa en el contenido de video subyacente cuando lo solicita el SDK de IMA. Si se activa la pausa y la reproducción cuando se solicita, el usuario no pierde partes del contenido de video cuando se muestran los anuncios.
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() } }
Eso es todo. Ahora está solicitando y mostrando anuncios con el SDK de IMA. Para aprender acerca de las funciones adicionales del SDK, consulta las otras guías o el muestras en GitHub.
Próximos pasos
Para maximizar los ingresos publicitarios en la plataforma de iOS, solicita permiso de Transparencia y seguimiento de apps para usar el IDFA.