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 veiculação de anúncios nos seus apps. Com os SDKs do IMA DAI, os apps fazem uma solicitação de transmissão para anúncios e vídeos de conteúdo, seja VOD ou conteúdo ao vivo. O SDK retorna uma transmissão de vídeo combinada para que você não precise alternar entre o anúncio e o vídeo de conteúdo no app.
Selecione a solução de DAI de seu interesse
DAI de serviço completo
Este guia demonstra como integrar o SDK do IMA DAI a um app de player de vídeo simples. Se você quiser conferir ou acompanhar uma integração de exemplo completa, faça o download do BasicExample no GitHub.
Visão geral da DAI do IMA
A implementação do IMA DAI envolve três componentes principais do SDK, conforme demonstrado neste guia:
IMAAdDisplayContainer
: um objeto de contêiner que fica acima do elemento de reprodução de vídeo e hospeda os elementos da interface do anúncio.IMAAdsLoader
: um objeto que solicita fluxos e processa eventos acionados por objetos de resposta de solicitação de fluxo. Você só precisa instanciar um carregador de anúncios, que pode ser reutilizado durante toda a vida útil do aplicativo.IMAStreamRequest
: umIMAVODStreamRequest
ou umIMALiveStreamRequest
: um objeto que define uma solicitação de stream. As solicitações de transmissão podem ser para transmissões ao vivo ou de vídeo on demand. As solicitações especificam um ID de conteúdo, uma chave de API ou token de autenticação e outros parâmetros.IMAStreamManager
: um objeto que processa streams de inserção de anúncios dinâmicos e interações com o back-end da DAI. O gerenciador de transmissão também processa pings de rastreamento e encaminha eventos de transmissão e de anúncio para o editor.
Pré-requisitos
Antes de começar, os seguintes itens são necessários:
- Xcode 13 ou mais recente
- CocoaPods (preferencial), Gerenciador de pacotes do Swift ou uma cópia salva do SDK do DAI do IMA para tvOS.
Criar um novo projeto do Xcode
No Xcode, crie um novo projeto tvOS usando Objective-C. Use BasicExample como o nome do projeto.
Adicionar o SDK do IMA DAI ao projeto do Xcode
Use um destes três métodos para instalar o SDK do IMA DAI.
Instalar o SDK usando o CocoaPods (preferencial)
O CocoaPods é um gerenciador de dependências para projetos do Xcode e é o método recomendado para instalar o SDK da DAI 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 DAI:
No mesmo diretório do arquivo BasicExample.xcodeproj, crie um arquivo de texto chamado Podfile e adicione a seguinte configuração:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '14' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0' 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 oferece suporte ao Gerenciador de pacotes Swift a partir da versão 4.8.2. Siga estas etapas para importar o pacote Swift.
No Xcode, instale o pacote Swift GoogleInteractiveMediaAds acessando File > Add Packages.
No prompt exibido, pesquise o repositório do GitHub do pacote Swift GoogleInteractiveMediaAds:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
Selecione a versão do pacote Swift do GoogleInteractiveMediaAds que você quer usar. Para novos projetos, recomendamos usar a próxima versão principal.
Quando terminar, o Xcode vai resolver as dependências do pacote e fazer o download delas em segundo plano. Para mais detalhes sobre como adicionar dependências de pacote, consulte o artigo da Apple.
Como fazer o download e instalar o SDK manualmente
Se você não quiser usar o Gerenciador de pacotes do Swift ou o CocoaPods, faça o download do SDK IMA DAI e adicione-o manualmente ao seu projeto.
Criar um player de vídeo simples
Primeiro, implemente um player de vídeo básico. Inicialmente, esse player não usa o SDK do IMA DAI nem contém nenhum método para acionar a reprodução.
ViewController.m
#import "ViewController.h"
#import <AVKit/AVKit.h>
@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach the video player to the view hierarchy.
[self addChildViewController:self.playerViewController];
self.playerViewController.view.frame = self.view.bounds;
[self.view addSubview:self.playerViewController.view];
[self.playerViewController didMoveToParentViewController:self];
}
@end
Importe o SDK e adicione stubs para interação com o IMA
Depois de adicionar o SDK do IMA DAI ao seu projeto, importe o SDK e adicione stubs para os pontos principais da interação do IMA.
ViewController.m
#import "ViewController.h"
#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach the video player to the view hierarchy.
[self addChildViewController:self.playerViewController];
self.playerViewController.view.frame = self.view.bounds;
[self.view addSubview:self.playerViewController.view];
[self.playerViewController didMoveToParentViewController:self];
[self attachAdContainer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestStream];
}
- (void)setupAdsLoader {}
- (void)attachAdContainer {}
- (void)requestStream {}
@end
Implementar o IMAAdsLoader
Em seguida, instancie o IMAAdsLoader
e anexe a visualização do contêiner de anúncios à
hierarquia de visualização.
ViewController.m
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)attachAdContainer {
self.adContainerView = [[UIView alloc] init];
[self.view addSubview:self.adContainerView];
self.adContainerView.frame = self.view.bounds;
}
Fazer uma solicitação de stream
Crie algumas constantes para armazenar as informações do stream e implemente a função de solicitação de stream para fazer a solicitação.
ViewController.m
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
@interface ViewController ()
...
- (void)requestStream {
IMAAVPlayerVideoDisplay *videoDisplay =
[[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
IMAAdDisplayContainer *adDisplayContainer =
[[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
adDisplayContainer:adDisplayContainer
videoDisplay:videoDisplay];
// VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
// to switch from a livestream to a VOD stream.
// IMAVODStreamRequest *request =
// [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
// videoId:kVideoID
// adDisplayContainer:adDisplayContainer
// videoDisplay:videoDisplay];
[self.adsLoader requestStreamWithRequest:request];
}
Processar eventos de transmissão
Os eventos IMAAdsLoader
e IMAStreamManager
acionam eventos que são usados para processar
inicialização, erros e mudanças no estado do stream. Esses eventos são acionados nos
protocolos IMAAdsLoaderDelegate
e IMAStreamManagerDelegate
. Detecte
um evento de anúncio carregado e inicialize o stream. Se um anúncio não carregar, transmita uma
cópia de backup.
ViewController.m
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
@"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
...
[self.adsLoader requestStreamWithRequest:request];
}
- (void)playBackupStream {
NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
[self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
[self.playerViewController.player play];
}
#pragma mark - IMAAdsLoaderDelegate
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Initialize and listen to stream manager's events.
self.streamManager = adsLoadedData.streamManager;
self.streamManager.delegate = self;
[self.streamManager initializeWithAdsRenderingSettings:nil];
NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Fall back to playing the backup stream.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self playBackupStream];
}
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}
- (void)streamManager:(IMAStreamManager *)streamManager
adDidProgressToTime:(NSTimeInterval)time
adDuration:(NSTimeInterval)adDuration
adPosition:(NSInteger)adPosition
totalAds:(NSInteger)totalAds
adBreakDuration:(NSTimeInterval)adBreakDuration {}
@end
Processar eventos de registro e erro
Vários eventos podem ser processados pelo delegado do gerenciador de stream, mas, para implementações básicas, os usos mais importantes são para realizar o registro de eventos, evitar ações de busca enquanto os anúncios são veiculados e processar erros.
ViewController.m
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
NSLog(@"StreamManager event (%@).", event.typeString);
switch (event.type) {
case kIMAAdEvent_STARTED: {
// Log extended data.
NSString *extendedAdPodInfo = [[NSString alloc]
initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
@"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];
NSLog(@"%@", extendedAdPodInfo);
break;
}
case kIMAAdEvent_AD_BREAK_STARTED: {
// Prevent user seek through when an ad starts and show the ad controls.
self.adContainerView.hidden = NO;
break;
}
case kIMAAdEvent_AD_BREAK_ENDED: {
// Allow user seek through after an ad ends and hide the ad controls.
self.adContainerView.hidden = YES;
break;
}
default:
break;
}
}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
// Fall back to playing the backup stream.
NSLog(@"StreamManager error: %@", error.message);
[self playBackupStream];
}
@end
Pronto! Agora você está solicitando e exibindo anúncios com o SDK do DAI do IMA. Para saber mais sobre recursos avançados do SDK, consulte os outros guias ou os exemplos no GitHub.