Começar

Pré-requisitos

• Xcode 13 ou versões mais recentes

Este guia descreve como invocar o SDK do PAL para receber um nonce e monitorar eventos de reprodução. Para acompanhar o guia completo, faça o download do aplicativo de amostra PAL tvOS.

Adicionar o SDK do PAL ao seu projeto

Instalar o SDK do PAL usando o Swift Package Manager

O SDK da biblioteca de acesso programático é compatível com o Swift Package Manager a partir da versão 2.5.3. Siga as etapas abaixo para importar o pacote Swift.

1. No Xcode, instale o pacote Swift do SDK do IMA acessando File > Add Packages….

2. No comando que aparece, pesquise o repositório do GitHub do pacote Swift do SDK do IMA:

   https://github.com/googleads/swift-package-manager-google-programmatic-access-library-tvos
   

3. Selecione a versão do pacote Swift do SDK PAL que você quer usar. Para novos projetos, recomendamos usar a opção Up to Next Major Version.

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 manualmente o SDK do PAL

Se você não quiser usar o Gerenciador de pacotes do Swift, baixe o SDK PAL e adicione-o manualmente ao seu projeto.

1. Faça o download e extraia o SDK do PAL para tvOS.
2. Siga o Guia do desenvolvedor da Apple para incorporar a estrutura ao seu projeto.

Gerar um valor de uso único

Um "nonce" é uma única string criptografada gerada pela PAL usando o PALNonceLoader. O SDK PAL exige que cada nova solicitação de stream seja acompanhada por um nonce recém-gerado. No entanto, os nonces podem ser reutilizados para várias solicitações de anúncio no mesmo fluxo.

Todos os snippets de código abaixo são modificações em ViewController.m no aplicativo de exemplo PAL tvOS.

Para solicitar um nonce, comece importando a biblioteca PAL:

@import ProgrammaticAccessLibrary;

Observação: recomendamos que você crie apenas uma instância da classe PALNonceLoader para cada sessão de usuário no seu app, a menos que ele tenha várias páginas ou construções equivalentes. Isso mantém o correlator de página, ou parâmetro &correlator, inalterado durante o ciclo de vida de uma página ou de uma sessão do app de um usuário.

Você ainda tem controle sobre o correlacionador de fluxo, ou &scor, que precisa ser redefinido uma vez para cada novo fluxo. Todas as solicitações de anúncios do mesmo fluxo precisam compartilhar o mesmo valor de PALNonceLoader e de correlação de fluxo para que os recursos de limite de frequência e exclusão competitiva funcionem corretamente.

Em seguida, crie uma instância do PALNonceLoader e adicione stubs para os dois métodos delegados:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The view in which a video would play.
// In this sample, it is mocked for simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end
...
- (void) viewDidLoad {
  [super viewDidLoad];
  // The default value for 'directedForChildOrUnknownAge' is
  // 'NO'. Update the value after the appropriate consent has been gathered.
  // By default, PAL automatically determines whether to enable limited ads
  // based on the user's TCF (Transparency and Consent Framework) consent data
  // on the device. If you must manually override the default behavior,
  // for example, to meet your app's requirements, use the
  // `PALSettings.forceLimitedAds` property.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.directedForChildOrUnknownAge = NO;

  self.nonceLoader = [[PALNonceLoader alloc] initWithSettings:settings];
  self.nonceLoader.delegate = self;
}

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
}

Em seguida, inicie uma solicitação de nonce, preencha as propriedades dela e use-a para inicializar um gerenciador de nonce:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The nonce manager result from the last successful nonce request.
@property(nonatomic) PALNonceManager *nonceManager;
// The view in which a video would play. In this sample, it is mocked for
// simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end

...

- (void)viewDidLoad {
  ...
  self.nonceLoader.delegate = self;
  [self requestNonceManager];
}

...

#pragma mark - UI Callback methods

/**
 * Requests a new nonce manager with a request containing arbitrary test values
 * like a (sane) user might supply. Displays the nonce or error on success. This
 * should be called once per stream.
 *
 * The PALNonceRequest parameters set here are example parameters.
 * You should set your parameters based on your own app characteristics.
 */
- (void)requestNonceManager {
  PALNonceRequest *request = [[PALNonceRequest alloc] init];
  request.continuousPlayback = PALFlagOff;
  request.descriptionURL = [NSURL URLWithString:@"https://example.com/desc?key=val"];
  request.iconsSupported = YES;
  request.playerType = @"AwesomePlayer";
  request.playerVersion = @"4.2.1";
  request.PPID = @"123987456";
  request.sessionID = @"Sample SID";
  // Sample API framework integers. See reference docs for more details.
  request.supportedAPIFrameworks = [NSMutableSet setWithArray:@[ @2, @7, @9 ]];
  request.videoPlayerHeight = 480;
  request.videoPlayerWidth = 640;
  request.willAdAutoPlay = PALFlagOn;
  request.willAdPlayMuted = PALFlagOff;

  if (self.nonceManager) {
    // Detach the old nonce manager's gesture recognizer before destroying it.
    [self.videoView removeGestureRecognizer:self.nonceManager.gestureRecognizer];
    self.nonceManager = nil;
  }
  [self.nonceLoader loadNonceManagerWithRequest:request];
}

Por fim, preencha os delegados do carregador de nonce para registrar nonces gerados:

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
  NSLog(@"Programmatic access nonce: %@", nonceManager.nonce);
  // Capture the created nonce manager and attach its gesture recognizer to the video view.
  self.nonceManager = nonceManager;
  [self.videoView addGestureRecognizer:self.nonceManager.gestureRecognizer];
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
  NSLog(@"Error generating programmatic access nonce: %@", error);
}

Ao fazer sua chamada VAST direta (DVC), defina o nonce como o valor no parâmetro givn. O valor de uso único é seguro para URL. Não é necessário codificar com URL.

Atenção: se você já forneceu um valor de uso único com o parâmetro paln, é altamente recomendável migrar para givn e parar de enviar paln. Se os dois parâmetros forem incluídos, o comportamento será indefinido em relação a qual nonce será usado.

Por fim, adicione métodos para enviar informações e cliques da sessão de reprodução de conteúdo ao SDK. Confira o exemplo a seguir que implementa os métodos sendPlaybackStart, sendPlaybackEnd e sendAdClick:

...

// Reports the start of playback for the current content session.
- (void)sendPlaybackStart {
  [self.nonceManager sendPlaybackStart];
}

// Reports the end of playback for the current content session.
- (void)sendPlaybackEnd {
  [self.nonceManager sendPlaybackEnd];
}

// Reports an ad click for the current nonce manager, if not nil.
- (void)sendAdClick {
  [self.nonceManager sendAdClick];
}

Na sua implementação, sendPlaybackStart precisa ser chamado em "início do player de vídeo" quando a reprodução é iniciada pela primeira vez, em resposta a uma ação iniciada pelo usuário (clique para assistir) ou pelo app (reprodução automática). sendPlaybackEnd precisa ser chamado quando a reprodução termina, e sendAdClick precisa ser chamado sempre que o espectador clica em um anúncio.

(Opcional) Enviar indicadores do Google Ad Manager por servidores de anúncios de terceiros

Configure a solicitação do servidor de anúncios de terceiros para o Ad Manager. Depois de concluir as etapas a seguir, o parâmetro nonce será propagado do SDK do PAL, pelos servidores intermediários e, em seguida, para o Google Ad Manager. Isso permite uma monetização melhor com o Google Ad Manager.

Observação: se você usa várias soluções de terceiros, por exemplo, um servidor de SSAI de terceiros chamando outro servidor de anúncios de terceiros, verifique se o nonce criptografado do SDK PAL é encaminhado para cada terceiro.

Configure seu servidor de anúncios de terceiros para incluir o nonce na solicitação do servidor ao Ad Manager. Confira um exemplo de tag de anúncio configurada no servidor de anúncios de terceiros:

https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...

Para mais detalhes, consulte o guia de implementação do lado do servidor do Google Ad Manager.

O Ad Manager procura givn= para identificar o valor de nonce. O servidor de anúncios terceirizado precisa ser compatível com uma macro própria, como %%custom_key_for_google_nonce%%, e substituí-la pelo parâmetro de consulta de nonce fornecido na etapa anterior. Mais informações sobre como fazer isso estão disponíveis na documentação do servidor de anúncios terceirizado.