Os SDKs do IMA facilitam a integração de anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer servidor de anúncios compatível com VAST e gerenciar a reprodução de anúncios nos seus apps. Com os SDKs do lado do cliente do IMA, você mantém o controle da reprodução de vídeo de conteúdo, enquanto o SDK processa a reprodução de anúncios. Os anúncios são veiculados em um player de vídeo separado, posicionado acima do player de vídeo de conteúdo do app.
Este guia demonstra como integrar o SDK do IMA a um app de player de vídeo. Se você quiser ver ou acompanhar um exemplo de integração concluída, baixe o BasicExample do GitHub.
Visão geral do lado do cliente da IMA
A implementação do IMA do lado do cliente envolve quatro componentes principais do SDK, que são demonstrados neste guia:
IMAAdDisplayContainer
: um objeto contêiner que especifica onde a IMA renderiza elementos da interface do anúncio e mede a visibilidade, incluindo o Active View e a Medição aberta.IMAAdsLoader
: um objeto que solicita anúncios e processa eventos de respostas de solicitação de anúncios. Você só precisa instanciar um carregador de anúncios, que pode ser reutilizado durante toda a vida útil do aplicativo.IMAAdsRequest
: um objeto que define uma solicitação de anúncio. As solicitações de anúncios especificam o URL da tag de anúncio VAST, além de outros parâmetros, como dimensões do anúncio.IMAAdsManager
: um objeto que contém a resposta à solicitação de anúncios, controla a reprodução de anúncios e detecta eventos de anúncio acionados pelo SDK.
Pré-requisitos
Antes de começar, os seguintes itens são necessários:
- Xcode 13 ou mais recente
- CocoaPods (preferencial), Swift Package Manager ou uma cópia baixada do SDK da IMA para iOS
1. Criar um projeto do Xcode
No Xcode, crie um novo projeto do iOS usando Objective-C ou Swift. Use BasicExample como o nome do projeto.
2. Adicionar o SDK do IMA ao projeto do Xcode
Instalar o SDK usando o CocoaPods (recomendado)
O CocoaPods é um gerenciador de dependências para projetos do Xcode e é o método recomendado para instalar o SDK do IMA. Para mais informações sobre como instalar ou usar o CocoaPods, consulte a documentação do CocoaPods. Depois de instalar o CocoaPods, use as instruções a seguir para instalar o SDK do IMA:
No mesmo diretório do arquivo BasicExample.xcodeproj, crie um arquivo de texto chamado Podfile e adicione a seguinte configuração:
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
No diretório que contém o Podfile, execute
pod install --repo-update
.Para verificar se a instalação foi bem-sucedida, abra o arquivo BasicExample.xcworkspace e confirme se ele contém dois projetos: BasicExample e Pods (as dependências instaladas pelo CocoaPods).
Instalar o SDK usando o Gerenciador de pacotes do Swift
O SDK do Interactive Media Ads é compatível com o Swift Package Manager a partir da versão 3.18.4. Para importar o pacote Swift, siga estas etapas:
No Xcode, instale o pacote Swift do SDK do IMA acessando Arquivo > Adicionar dependências do pacote….
No prompt, pesquise o repositório do GitHub do pacote Swift do SDK do IMA para iOS:
swift-package-manager-google-interactive-media-ads-ios
.Selecione a versão do pacote Swift do SDK do IMA que você quer usar. Para novos projetos, recomendamos usar a opção Até a próxima versão principal.
Depois disso, o Xcode resolve as dependências do pacote e faz o download delas em segundo plano. Para mais detalhes sobre como adicionar dependências de pacotes, consulte o artigo da Apple.
Fazer o download e instalar o SDK manualmente
Se você não quiser usar o Gerenciador de pacotes do Swift ou o CocoaPods, baixe o SDK do IMA e adicione-o manualmente ao seu projeto.
3. Criar um player de vídeo
Primeiro, implemente um player de vídeo. Inicialmente, esse player não usa o SDK do IMA e não contém nenhum método para acionar a reprodução.
Objective-C
Importe as dependências do player:
#import "ViewController.h"
@import AVFoundation;
Configure as variáveis do player:
@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;
Inicie o player de vídeo quando a visualização for carregada:
@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
Importe as dependências do player:
import AVFoundation
Configure as variáveis do player:
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)
}()
Inicie o player de vídeo quando a visualização for carregada:
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. Importar o SDK do IMA
Para importar o SDK do IMA, faça o seguinte:
Objective-C
Importe o SDK do IMA:
@import GoogleInteractiveMediaAds;
Crie variáveis para as classes
IMAAdsLoader
,IMAAVPlayerContentPlayhead
eIMAAdsManager
usadas no 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
Importe o SDK do IMA:
import GoogleInteractiveMediaAds
Crie variáveis para as classes
IMAAdsLoader
,IMAAVPlayerContentPlayhead
eIMAAdsManager
usadas no 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. Implementar o rastreador de cabeça de reprodução de conteúdo e o observador de fim de stream
Para veicular anúncios no meio do vídeo, o SDK do IMA precisa rastrear a posição atual
do conteúdo de vídeo. Para fazer isso, crie uma classe que implemente
IMAContentPlayhead
. Se você estiver usando um AVPlayer
, como mostrado neste exemplo,
o SDK fornece a classe IMAAVPlayerContentPlayhead
, que faz isso por você.
Se você não estiver usando AVPlayer
, vai precisar implementar IMAContentPlayhead
em
uma classe própria.
Você também precisa informar ao SDK quando o conteúdo terminar de ser reproduzido para que ele possa
mostrar anúncios pós-vídeo. Para isso, chame o método
contentComplete
no IMAAdsLoader usando AVPlayerItemDidPlayToEndTimeNotification
.
Objective-C
Crie a instância IMAAVPlayerContentPlayhead
na configuração do player:
// 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];
Crie o método contentDidFinishPlaying()
para chamar
IMAAdsLoader.contentComplete()
quando o conteúdo terminar de ser reproduzido:
- (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
Crie o observador de fim de conteúdo na configuração do player:
NotificationCenter.default.addObserver(
self,
selector: #selector(contentDidFinishPlaying(_:)),
name: .AVPlayerItemDidPlayToEndTime,
object: contentPlayer.currentItem)
Crie o método contentDidFinishPlaying()
para chamar
IMAAdsLoader.contentComplete()
quando o conteúdo terminar de ser reproduzido:
@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. Inicializar o carregador de anúncios e fazer uma solicitação de anúncios
Para solicitar um conjunto de anúncios, crie uma instância de IMAAdsLoader
.
Esse carregador pode ser usado para processar objetos IMAAdsRequest
associados a um URL de tag de anúncio especificado.
Como prática recomendada, mantenha apenas uma instância de IMAAdsLoader
durante todo o ciclo de vida do app. Para fazer outras solicitações de anúncio, crie um novo objeto IMAAdsRequest
, mas reutilize o mesmo IMAAdsLoader
. Para mais informações, consulte as Perguntas frequentes sobre o SDK do 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. Configurar um delegado do carregador de anúncios
Em um evento de carregamento bem-sucedido, o IMAAdsLoader
chama o método
adsLoadedWithData
do delegado atribuído, transmitindo a ele uma instância de IMAAdsManager
. Em seguida, você pode inicializar o gerenciador de anúncios, que carrega os anúncios individuais, conforme definido pela resposta ao URL da tag de anúncio.
Além disso, processe os erros que possam ocorrer durante o processo de carregamento. Se os anúncios não carregarem, verifique se a reprodução de mídia continua sem anúncios para não interferir na experiência do usuário.
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. Configurar um delegado do gerenciador de anúncios
Por fim, para gerenciar eventos e mudanças de estado, o gerenciador de anúncios precisa de um delegado próprio. O IMAAdManagerDelegate
tem métodos para processar eventos e erros de anúncios,
além de métodos para acionar a reprodução e a pausa no conteúdo de vídeo.
Iniciar reprodução
Aguarde o evento LOADED
para iniciar a reprodução de conteúdo e anúncios. Para mais
detalhes, consulte
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()
}
}
Solucionar erros
Adicione também um handler para erros de anúncio. Se ocorrer um erro, como na etapa anterior, retome a reprodução do conteúdo.
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()
}
Detectar eventos de tocar e pausar
Os dois últimos métodos delegados que você precisa implementar são usados para acionar eventos de reprodução e pausa no conteúdo de vídeo subjacente, quando solicitado pelo SDK do IMA. Acionar a pausa e a reprodução quando solicitado evita que o usuário perca partes do conteúdo de vídeo quando os anúncios são exibidos.
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()
}
Pronto! Agora você está solicitando e mostrando anúncios com o SDK do IMA. Para saber mais sobre outros recursos do SDK, consulte os outros guias ou os exemplos no GitHub.
Próximas etapas
Para maximizar a receita de publicidade na plataforma iOS, solicite permissão de transparência e rastreamento de apps para usar o IDFA.