Los SDK de IMA facilitan la integración de anuncios multimedia en tus sitios web y apps. Los SDK de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administrar la reproducción de anuncios en tus apps. Con los SDK de IMA del cliente, mantienes el control de la reproducción de video de contenido, mientras que el SDK controla la reproducción de anuncios. Los anuncios se reproducen en un reproductor de video independiente que se ubica sobre el reproductor de video de contenido de la app.
En esta guía, se muestra cómo integrar el SDK de IMA en una app de reproductor de video. Para ver o seguir una integración de muestra completa, descarga el BasicExample de GitHub.
Descripción general del cliente de IMA
La implementación del cliente de IMA implica cuatro componentes principales del SDK. En esta guía, se muestran estos componentes:
IMAAdDisplayContainer: Es un objeto contenedor que especifica dónde IMA renderiza los elementos de la IU de los anuncios y mide la visibilidad, incluidos Vista activa y Open Measurement.IMAAdsLoader: Es un objeto que solicita anuncios y controla los eventos de las respuestas de solicitud de anuncios. Solo debes crear una instancia de un cargador de anuncios, que se puede reutilizar durante la vida útil de la aplicación.IMAAdsRequest: Es 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: Es un objeto que contiene la respuesta a la solicitud de anuncios, controla la reproducción de anuncios y detecta los eventos de anuncios que activa el SDK.
Requisitos previos
Antes de comenzar, necesitas lo siguiente:
- Xcode 13 o una versión más reciente
- Método para instalar el SDK de IMA:
- Preferido: Swift Package Manager
- CocoaPods
- Una copia descargada del SDK de IMA para tvOS
1. Crea un nuevo proyecto de Xcode
En Xcode, crea un nuevo proyecto de tvOS con Objective-C o Swift. Usa BasicExample como nombre del proyecto.
2. Agrega el SDK de IMA al proyecto de Xcode
Para instalar el SDK de IMA, elige un método preferido.
Recomendado: Instala el SDK de IMA con Swift Package Manager
El SDK de anuncios multimedia interactivos admite Swift Package Manager a partir de la versión 4.8.2. Sigue estos pasos para importar el paquete de Swift.
En Xcode, instala el paquete de Swift del SDK de IMA. Para ello, navega a File > Add Packages... (Archivo > Agregar paquetes...).
En el mensaje que aparece, busca el repositorio de GitHub del paquete de Swift del SDK de IMA:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosSelecciona la versión del paquete de Swift del SDK de IMA que deseas usar. Para los proyectos nuevos, te recomendamos que uses la opción Up to Next Major Version (Hasta la siguiente versión principal).
Cuando termines, Xcode resolverá las dependencias de tu paquete y las descargará en segundo plano. Para obtener más detalles sobre cómo agregar dependencias de paquetes, consulta el artículo de Apple.
Instala el SDK de IMA con CocoaPods
Para instalar el SDK de IMA, usa CocoaPods. Para obtener más información sobre la instalación o el uso de CocoaPods, consulta la documentación de CocoaPods. Después de instalar CocoaPods, haz lo siguiente:
En el mismo directorio en que está el archivo BasicExample.xcodeproj, crea un archivo de texto llamado Podfile y agrega la siguiente configuración:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0' endDesde el directorio que contiene el Podfile, ejecuta
pod install --repo-update.Para verificar que la instalación se haya realizado correctamente, abre el archivo BasicExample.xcworkspace y confirma que contiene dos proyectos: BasicExample y Pods (las dependencias instaladas por CocoaPods).
Descarga e instala el SDK de IMA de forma manual
Si no quieres usar Swift Package Manager, descarga y agrega el SDK de IMA de forma manual a tu proyecto.
3. Importa el SDK de IMA
Agrega el framework de IMA con una instrucción de importación.
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4. Crea un reproductor de video e integra el SDK de IMA
En el siguiente ejemplo, se inicializa el SDK de IMA:
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&cmsid=496&vid=short_onecue&correlator=";
@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
[self setupContentPlayer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestAds];
}
// 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 resume events from the
// remote and play content underneath the ad.
[self.contentPlayerViewController willMoveToParentViewController:nil];
[self.contentPlayerViewController.view removeFromSuperview];
[self.contentPlayerViewController removeFromParentViewController];
}
Swift
class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
static let contentURLString =
"https://devstreaming-cdn.apple.com/videos/streaming/examples/"
+ "img_bipbop_adv_example_fmp4/master.m3u8"
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&correlator="
var adsLoader: IMAAdsLoader!
var adDisplayContainer: IMAAdDisplayContainer!
var adsManager: IMAAdsManager!
var contentPlayhead: IMAAVPlayerContentPlayhead?
var playerViewController: AVPlayerViewController!
var adBreakActive = false
deinit {
NotificationCenter.default.removeObserver(self)
}
override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor.black
setUpContentPlayer()
setUpAdsLoader()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
requestAds()
}
En este ejemplo, viewDidLoad() inicializa IMAAdsLoader, y viewDidAppear() solicita anuncios una vez que la vista es visible. Los métodos de ayuda showContentPlayer() y hideContentPlayer() activan o desactivan la visibilidad del contenido durante la reproducción de anuncios.
En este ejemplo, se usa la variable constante adTagURLString para definir la etiqueta de anuncio de VAST para la solicitud de anuncio y los siguientes componentes para administrar el SDK de IMA:
adsLoader: Controla las solicitudes y respuestas de anuncios. Te recomendamos que uses una sola instancia para el ciclo de vida de la app.adDisplayContainer: Especifica la vista para renderizar anuncios.adsManager: Administra la reproducción de anuncios y detecta los eventos de anuncios.contentPlayhead: Realiza un seguimiento del progreso del contenido para activar las pausas publicitarias de anuncios durante el video.adBreakActive: Indica si se está reproduciendo una pausa publicitaria para evitar la búsqueda de anuncios.
5. Implementa el seguimiento del cabezal de reproducción del contenido y el observador de fin 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 pasar la posición actual a IMA, crea una clase que implemente IMAContentPlayhead. Si usas un AVPlayer, como se muestra en este ejemplo, el SDK de IMA proporciona la clase IMAAVPlayerContentPlayhead para pasar la información de la posición actual. Si no usas AVPlayer, implementa IMAContentPlayhead en una clase propia.
Objective-C
- (void)setupContentPlayer {
// Create a content video player. Create a playhead to track content progress so the SDK knows
// when to play ads in a VMAP playlist.
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];
}
Swift
func setUpContentPlayer() {
// Load AVPlayer with path to our content.
let contentURL = URL(string: ViewController.contentURLString)!
let player = AVPlayer(url: contentURL)
playerViewController = AVPlayerViewController()
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)
showContentPlayer()
}
Configura un objeto de escucha para llamar a contentComplete en IMAAdsLoader cuando finalice el contenido, con AVPlayerItemDidPlayToEndTimeNotification. Llamar a contentComplete permite que el SDK de IMA sepa cuándo termina de reproducirse el contenido para mostrar anuncios posteriores al video.
Objective-C
- (void)contentDidFinishPlaying:(NSNotification *)notification {
// Notify the SDK that the postrolls should be played.
[self.adsLoader contentComplete];
}
- (void)dealloc {
[[NSNotificationCenter defaultCenter] removeObserver:self];
}
Swift
@objc func contentDidFinishPlaying(_ notification: Notification) {
adsLoader.contentComplete()
}
6. Inicializa el cargador de anuncios y realiza una solicitud de anuncios
Para solicitar un conjunto de anuncios, crea una instancia de IMAAdsLoader.
Este cargador procesa objetos IMAAdsRequest asociados con una URL de etiqueta de anuncio especificada.
Como práctica recomendada, mantén solo una instancia de IMAAdsLoader para todo el ciclo de vida de tu app. Para realizar solicitudes de anuncios adicionales, crea un objeto IMAAdsRequest nuevo, pero reutiliza el mismo IMAAdsLoader. Para obtener más
información, consulta las Preguntas frecuentes del SDK de IMA.
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)requestAds {
// Pass the main view as the container for ad display.
self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
viewController:self];
IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
adDisplayContainer:self.adDisplayContainer
contentPlayhead:self.contentPlayhead
userContext:nil];
[self.adsLoader requestAdsWithRequest:request];
}
Swift
func setUpAdsLoader() {
adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self
}
func requestAds() {
// Create ad display container for ad rendering.
adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view, viewController: self)
// 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)
}
7. Configura un delegado del cargador de anuncios
En un evento de carga exitoso, IMAAdsLoader llama al método adsLoadedWithData de su delegado asignado y le pasa una instancia de IMAAdsManager.
Después de tener la instancia de IMAAdsManager, inicializa el administrador de anuncios, que carga anuncios individuales según la respuesta de la URL de la etiqueta de anuncio.
Para los eventos de carga sin éxito, configura un delegado de IMAAdsLoader para controlar los errores que se producen durante el proceso de carga. Si los anuncios no se cargan, asegúrate de que la reproducción de contenido multimedia continúe sin anuncios para que los usuarios puedan ver el contenido multimedia.
Objective-C
#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.delegate = self;
[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];
}
Swift
func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
// Grab the instance of the IMAAdsManager and set ourselves as the delegate.
adsManager = adsLoadedData.adsManager
adsManager.delegate = self
adsManager.initialize(with: nil)
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
8. Configura un delegado del administrador de anuncios
Por último, para administrar los eventos y los cambios de estado, el administrador de anuncios requiere su propio delegado. IMAAdManagerDelegate tiene métodos para controlar eventos y errores de anuncios, así como métodos para activar la reproducción y la pausa en tu contenido de video.
Cómo iniciar la reproducción
El método didReceiveAdEvent controla todos los eventos IMAAdEvent.
Para este ejemplo básico, detecta el evento LOADED para indicarle al administrador de anuncios que inicie la reproducción de contenido y anuncios. El SDK de IMA activa el evento ICON_FALLBACK_IMAGE_CLOSED cuando el usuario cierra un diálogo de ícono de resguardo después de presionar un ícono. Después de esta acción, se reanuda la reproducción de anuncios.
Objective-C
#pragma mark - IMAAdsManagerDelegate
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
switch (event.type) {
case kIMAAdEvent_LOADED: {
// Play each ad once it has loaded.
[adsManager start];
break;
}
case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
// Resume ad after user has closed dialog.
[adsManager resume];
break;
}
default:
break;
}
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
switch event.type {
case IMAAdEventType.LOADED:
// Play each ad once it has been loaded.
adsManager.start()
case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
// Resume playback after the user has closed the dialog.
adsManager.resume()
default:
break
}
}
Maneja los errores
Agrega también un controlador para los errores de anuncios. Si se produce un error, como en el paso anterior, reanuda la reproducción de contenido.
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];
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
// Fall back to playing content
print("AdsManager error: \(error.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
Activa eventos de reproducción y pausa
Los dos últimos métodos delegados que implementas activan eventos de reproducción y pausa en el contenido de video subyacente cuando el SDK de IMA los solicita. Activar la pausa y la reproducción cuando el SDK de IMA los solicita evita que el usuario se pierda partes del contenido de video cuando se muestran los anuncios.
Objective-C
- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
// Pause the content for the SDK to play ads.
[self.contentPlayerViewController.player pause];
[self hideContentPlayer];
// Trigger an update to send focus to the ad display container.
self.adBreakActive = YES;
[self setNeedsFocusUpdate];
}
- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
// Resume the content since the SDK is done playing ads (at least for now).
[self showContentPlayer];
[self.contentPlayerViewController.player play];
// Trigger an update to send focus to the content player.
self.adBreakActive = NO;
[self setNeedsFocusUpdate];
}
Swift
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
// Pause the content for the SDK to play ads.
playerViewController.player?.pause()
hideContentPlayer()
// Trigger an update to send focus to the ad display container.
adBreakActive = true
setNeedsFocusUpdate()
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
// Resume the content since the SDK is done playing ads (at least for now).
showContentPlayer()
playerViewController.player?.play()
// Trigger an update to send focus to the content player.
adBreakActive = false
setNeedsFocusUpdate()
}
Eso es todo. Ahora solicitas y muestras anuncios con el SDK de IMA. Para obtener información sobre las funciones adicionales del SDK, consulta las otras guías o las muestras en GitHub.
Próximos pasos
Para maximizar los ingresos publicitarios en la plataforma tvOS, solicita el permiso de transparencia y seguimiento de aplicaciones para usar el IDFA.