Começar

Pré-requisitos

• Xcode 13 ou versão mais recente

Neste guia, descrevemos como invocar o SDK da PAL para receber um valor de uso único e monitorar eventos de reprodução. Para acompanhar o guia completo, faça o download do aplicativo de exemplo PAL tvOS (em inglês).

Adicionar o SDK da PAL ao seu projeto

Instalar o SDK da PAL usando o Gerenciador de pacotes do Swift

O SDK da biblioteca de acesso programático é compatível com o Gerenciador de pacotes Swift 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 navegando até File > Add Packages....

2. No prompt exibido, pesquise o repositório do Pacote Swift do SDK do IMA no GitHub:

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

3. Selecione a versão do pacote Swift do SDK da PAL que você quer usar. Para novos projetos, recomendamos o uso da 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 ver mais detalhes sobre como adicionar dependências de pacotes, consulte o artigo da Apple.

Fazer o download e instalar manualmente o SDK da PAL

Se você não quiser usar o Gerenciador de pacotes do Swift, faça o download do SDK da PAL e adicione-o manualmente ao projeto.

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

Gerar um valor de uso único

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

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

Para solicitar um valor de uso único, 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 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 a sessão de um usuário no app.

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

Em seguida, crie uma instância do PALNonceLoader e adicione stubs aos 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 'allowStorage' and
  // 'directedForChildOrUnknownAge' is 'NO', but should be updated once the
  // appropriate consent has been gathered. Publishers should either
  // integrate with a CMP or use a different method to handle storage consent.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.allowStorage = YES;
  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 valor de uso único, preencha as propriedades e use-a para inicializar um gerenciador de valor de uso único:

@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.
 */
- (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 integer. See reference docs for more details.
  NSInteger SampleAPIFramework = 501;
  request.supportedApiFrameworks = [NSMutableSet setWithArray:@[ SampleAPIFramework ]];
  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 uso único para registrar valores de uso único 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, na sigla em inglês), defina o valor de uso único como o valor no parâmetro givn. O valor de uso único é seguro para URL. Não é necessário codificá-lo para URL.

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

Por fim, é necessário adicionar métodos para processar o envio de informações da sessão de reprodução de conteúdo e cliques ao SDK. Confira o exemplo a seguir implementando 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 "iniciar player de vídeo" quando a reprodução é iniciada pela primeira vez, em resposta a uma ação iniciada pelo usuário (clique para reproduzir) ou uma ação iniciada 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

Configurar a solicitação do servidor de anúncios de terceiros para o Ad Manager. Depois de concluir as etapas a seguir, o parâmetro de valor de uso único é propagado a partir do SDK da PAL, por meio dos servidores intermediários e, em seguida, para o Google Ad Manager. Isso permite uma melhor monetização por meio do Google Ad Manager.

Observação :se você usa várias soluções de terceiros, por exemplo, um servidor SSAI de terceiros chamando outro servidor de anúncios de terceiros, é necessário garantir que o valor de uso único criptografado do SDK da PAL seja encaminhado para cada terceiro.

Configure seu servidor de anúncios de terceiros para incluir o valor de uso único na solicitação do servidor para o Ad Manager. Veja um exemplo de uma tag de anúncio configurada dentro do 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 servidor do Google Ad Manager.

O Ad Manager procura givn= para identificar o valor de uso único. O servidor de anúncios de terceiros precisa oferecer suporte a alguma macro própria, como %%custom_key_for_google_nonce%%, e substituí-la pelo parâmetro de consulta de uso único fornecido na etapa anterior. Mais informações sobre como fazer isso serão disponibilizadas na documentação do servidor de anúncios de terceiros.