Los SDKs de IMA facilitan la integración de anuncios multimedia en tus sitios web y aplicaciones. Los SDKs de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administrar la reproducción de anuncios en tus aplicaciones. Con los SDKs del cliente de IMA, 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 reproductor de video independiente 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 una app de reproductor de video. Si deseas ver o seguir una integración de ejemplo completa, descarga BasicExample desde GitHub.
Descripción general del IMA del cliente
La implementación del SDK de IMA del cliente implica cuatro componentes principales del SDK, que se demuestran en esta guía:
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 eventos de las respuestas a las solicitudes de anuncios. Solo debes crear una instancia del 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
: Objeto que contiene la respuesta a la solicitud de anuncios, controla la reproducción de anuncios y escucha los eventos de anuncios que activa el SDK.
Requisitos previos
Antes de comenzar, necesitas lo siguiente:
- Xcode 13 o una versión posterior
- CocoaPods (preferido), Swift Package Manager o una copia descargada del SDK de IMA para iOS
1. Crea un proyecto nuevo de Xcode
En Xcode, crea un nuevo proyecto para iOS con Objective-C o Swift. Usa BasicExample como nombre del proyecto.
2. Agrega el SDK de IMA al proyecto de Xcode
Instala el SDK con CocoaPods (recomendado)
CocoaPods es un administrador de dependencias para proyectos de Xcode y es el método recomendado para instalar el SDK de IMA. Para obtener más información sobre la instalación o el uso de CocoaPods, consulta la documentación de CocoaPods. Una vez que hayas instalado CocoaPods, sigue estas instrucciones para instalar el SDK de IMA:
En el mismo directorio que tu archivo BasicExample.xcodeproj, crea un archivo de texto llamado Podfile y agrega la siguiente configuración:
Objective-C
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '12' target "BasicExample" do pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end
Swift
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '12' target "BasicExample" do pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end
Desde 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 contenga 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. Para importar el paquete de Swift, completa los siguientes pasos:
En Xcode, instala el paquete Swift del SDK de IMA. Para ello, navega a File > Add Package Dependencies….
En la instrucción, busca el repositorio de GitHub del paquete de Swift del SDK de IMA para iOS:
swift-package-manager-google-interactive-media-ads-ios
.Selecciona la versión del paquete Swift del SDK de IMA que deseas usar. Para los proyectos nuevos, te recomendamos que uses la opción Up to Next Major Version.
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.
Descarga e instala el SDK de forma manual
Si no quieres usar Swift Package Manager ni CocoaPods, puedes descargar el SDK de IMA y agregarlo manualmente a tu proyecto.
3. Crea un reproductor de video
Primero, implementa un reproductor de video. Inicialmente, este reproductor no usa el SDK de IMA y no contiene ningún método para activar la reproducción.
Objective-C
Importa las dependencias del reproductor:
#import "ViewController.h"
@import AVFoundation;
Configura las variables del reproductor:
@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
/// Content video player.
@property(nonatomic, strong) AVPlayer *contentPlayer;
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;
/// UIView in which we will render our AVPlayer for content.
@property(nonatomic, weak) IBOutlet UIView *videoView;
Inicializa el reproductor de video cuando se cargue la vista:
@implementation ViewController
// The content URL to play.
NSString *const kTestAppContentUrl_MP4 =
@"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
// Ad tag
NSString *const kTestAppAdTagUrl = @"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=";
- (void)viewDidLoad {
[super viewDidLoad];
self.playButton.layer.zPosition = MAXFLOAT;
[self setupAdsLoader];
[self setUpContentPlayer];
}
#pragma mark Content Player Setup
- (void)setUpContentPlayer {
// Load AVPlayer with path to our content.
NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
self.contentPlayer = [AVPlayer playerWithURL:contentURL];
// Create a player layer for the player.
AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];
// Size, position, and display the AVPlayer.
playerLayer.frame = self.videoView.layer.bounds;
[self.videoView.layer addSublayer:playerLayer];
// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(contentDidFinishPlaying:)
name:AVPlayerItemDidPlayToEndTimeNotification
object:self.contentPlayer.currentItem];
}
- (IBAction)onPlayButtonTouch:(id)sender {
[self requestAds];
self.playButton.hidden = YES;
}
Swift
Importa las dependencias del reproductor:
import AVFoundation
Configura las variables del reproductor:
class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
static let contentURL = URL(
string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!
private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)
private lazy var playerLayer: AVPlayerLayer = {
AVPlayerLayer(player: contentPlayer)
}()
Inicializa el reproductor de video cuando se cargue la vista:
private lazy var videoView: UIView = {
let videoView = UIView()
videoView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(videoView)
NSLayoutConstraint.activate([
videoView.bottomAnchor.constraint(
equalTo: view.safeAreaLayoutGuide.bottomAnchor),
videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
])
return videoView
}()
// MARK: - View controller lifecycle methods
override func viewDidLoad() {
super.viewDidLoad()
videoView.layer.addSublayer(playerLayer)
adsLoader.delegate = self
NotificationCenter.default.addObserver(
self,
selector: #selector(contentDidFinishPlaying(_:)),
name: .AVPlayerItemDidPlayToEndTime,
object: contentPlayer.currentItem)
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
playerLayer.frame = videoView.layer.bounds
}
override func viewWillTransition(
to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator
) {
coordinator.animate { _ in
// do nothing
} completion: { _ in
self.playerLayer.frame = self.videoView.layer.bounds
}
}
// MARK: - Public methods
func playButtonPressed() {
requestAds()
}
4. Importa el SDK de IMA
Para importar el SDK de IMA, haz lo siguiente:
Objective-C
Importa el SDK de IMA:
@import GoogleInteractiveMediaAds;
Crea variables para las clases
IMAAdsLoader
,IMAAVPlayerContentPlayhead
yIMAAdsManager
que se usan en la app:// SDK /// Entry point for the SDK. Used to make ad requests. @property(nonatomic, strong) IMAAdsLoader *adsLoader; /// Playhead used by the SDK to track content video progress and insert mid-rolls. @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead; /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request. @property(nonatomic, strong) IMAAdsManager *adsManager;
Swift
Importa el SDK de IMA:
import GoogleInteractiveMediaAds
Crea variables para las clases
IMAAdsLoader
,IMAAVPlayerContentPlayhead
yIMAAdsManager
que se usan en la app: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=" private let adsLoader = IMAAdsLoader() private var adsManager: IMAAdsManager? private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = { IMAAVPlayerContentPlayhead(avPlayer: contentPlayer) }()
5. Implementa el observador de cabezal de reproducción de contenido y el observador de fin de transmisión
Para reproducir anuncios de mitad de video, el SDK de IMA debe hacer un seguimiento de la posición actual de tu contenido de video. Para ello, crea una clase que implemente IMAContentPlayhead
. Si usas un 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 finalice la reproducción de tu contenido para que pueda mostrar anuncios posteriores al video. Para ello, se llama al método contentComplete
en IMAAdsLoader, con AVPlayerItemDidPlayToEndTimeNotification
.
Objective-C
Crea la instancia IMAAVPlayerContentPlayhead
en la configuración del reproductor:
// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(contentDidFinishPlaying:)
name:AVPlayerItemDidPlayToEndTimeNotification
object:self.contentPlayer.currentItem];
Crea el método contentDidFinishPlaying()
para llamar a IMAAdsLoader.contentComplete()
cuando termine de reproducirse el contenido:
- (void)contentDidFinishPlaying:(NSNotification *)notification {
// Make sure we don't call contentComplete as a result of an ad completing.
if (notification.object == self.contentPlayer.currentItem) {
[self.adsLoader contentComplete];
}
}
Swift
Crea el observador de finalización del contenido en la configuración del reproductor:
NotificationCenter.default.addObserver(
self,
selector: #selector(contentDidFinishPlaying(_:)),
name: .AVPlayerItemDidPlayToEndTime,
object: contentPlayer.currentItem)
Crea el método contentDidFinishPlaying()
para llamar a IMAAdsLoader.contentComplete()
cuando termine de reproducirse el contenido:
@objc func contentDidFinishPlaying(_ notification: Notification) {
// Make sure we don't call contentComplete as a result of an ad completing.
if notification.object as? AVPlayerItem == contentPlayer.currentItem {
adsLoader.contentComplete()
}
}
6. Inicializa el cargador de anuncios y realiza 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 una URL de etiqueta de anuncio especificada.
Como práctica recomendada, mantén solo una instancia de IMAAdsLoader
durante 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 sobre el SDK de IMA.
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
self.adsLoader.delegate = self;
}
- (void)requestAds {
// Create an ad display container for ad rendering.
IMAAdDisplayContainer *adDisplayContainer =
[[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
viewController:self
companionSlots:nil];
// Create an ad request with our ad tag, display container, and optional user context.
IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
adDisplayContainer:adDisplayContainer
contentPlayhead:self.contentPlayhead
userContext:nil];
[self.adsLoader requestAdsWithRequest:request];
}
Swift
private func requestAds() {
// Create ad display container for ad rendering.
let adDisplayContainer = IMAAdDisplayContainer(
adContainer: videoView, viewController: self, companionSlots: nil)
// Create an ad request with our ad tag, display container, and optional user context.
let request = IMAAdsRequest(
adTagUrl: PlayerContainerViewController.adTagURLString,
adDisplayContainer: adDisplayContainer,
contentPlayhead: contentPlayhead,
userContext: nil)
adsLoader.requestAds(with: request)
}
7. Cómo configurar un delegado del cargador de anuncios
En un evento de carga exitosa, IMAAdsLoader
llama al método adsLoadedWithData
de su delegado asignado y le pasa una instancia de IMAAdsManager
. Luego, puedes inicializar el administrador de anuncios, que carga los anuncios individuales, según se define en la respuesta a la URL de la etiqueta del anuncio.
Además, asegúrate de controlar los errores que puedan ocurrir durante el proceso de carga. Si no se cargan los anuncios, asegúrate de que la reproducción de contenido multimedia continúe sin anuncios para no interferir en la experiencia del usuario.
Objective-C
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Grab the instance of the IMAAdsManager and set ourselves as the delegate.
self.adsManager = adsLoadedData.adsManager;
self.adsManager.delegate = self;
// Create ads rendering settings to tell the SDK to use the in-app browser.
IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
adsRenderingSettings.linkOpenerPresentingController = self;
// Initialize the ads manager.
[self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Something went wrong loading ads. Log the error and play the content.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self.contentPlayer 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
// Create ads rendering settings and tell the SDK to use the in-app browser.
let adsRenderingSettings = IMAAdsRenderingSettings()
adsRenderingSettings.linkOpenerPresentingController = self
// Initialize the ads manager.
adsManager?.initialize(with: adsRenderingSettings)
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
if let message = adErrorData.adError.message {
print("Error loading ads: \(message)")
}
contentPlayer.play()
}
8. Cómo configurar un delegado del administrador de anuncios
Por último, para administrar los eventos y los cambios de estado, el administrador de anuncios necesita su propio delegado. El objeto 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.
Iniciar reproducción
Espera el evento LOADED
para iniciar la reproducción de contenido y anuncios. Para obtener más información, consulta didReceiveAdEvent
.
Objective-C
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
// When the SDK notified us that ads have been loaded, play them.
if (event.type == kIMAAdEvent_LOADED) {
[adsManager start];
}
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
// When the SDK notifies us the ads have been loaded, play them.
if event.type == IMAAdEventType.LOADED {
adsManager.start()
}
}
Soluciona errores
También agrega un controlador para los errores de anuncios. Si se produce un error, como en el paso anterior, reanuda la reproducción del contenido.
Objective-C
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
// Something went wrong with the ads manager after ads were loaded. Log the error and play the
// content.
NSLog(@"AdsManager error: %@", error.message);
[self.contentPlayer play];
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
// Something went wrong with the ads manager after ads were loaded.
// Log the error and play the content.
if let message = error.message {
print("AdsManager error: \(message)")
}
contentPlayer.play()
}
Cómo detectar eventos de reproducción y pausa
Los dos últimos métodos de delegado que debes implementar se usan para activar eventos de reproducción y pausa en el contenido de video subyacente, cuando lo solicita el SDK de IMA. Activar la pausa y la reproducción cuando se solicita evita que el usuario se pierda partes del contenido de video cuando se muestran anuncios.
Objective-C
- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
// The SDK is going to play ads, so pause the content.
[self.contentPlayer pause];
}
- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
// The SDK is done playing ads (at least for now), so resume the content.
[self.contentPlayer play];
}
Swift
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
// The SDK is going to play ads, so pause the content.
contentPlayer.pause()
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
// The SDK is done playing ads (at least for now), so resume the content.
contentPlayer.play()
}
Eso es todo. Ahora solicitas y muestras anuncios con el SDK de IMA. Para obtener más información sobre las funciones adicionales del SDK, consulta las otras guías o los ejemplos en GitHub.
Próximos pasos
Para maximizar los ingresos publicitarios en la plataforma de iOS, solicita permiso de transparencia y seguimiento de aplicaciones para usar el IDFA.