Primeiros passos

Pré-requisitos

• Xcode 13 ou mais recente

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

Adicionar o SDK da PAL ao projeto

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

O SDK da biblioteca de acesso programático oferece suporte ao pacote Swift Manager a partir da versão 2.5.3. Siga o etapas abaixo para importar o pacote Swift.

1. No Xcode, instale o pacote Swift do SDK do IMA acessando Arquivo > Adicionar pacotes...

2. Na solicitação exibida, pesquise o pacote Swift do SDK do IMA no GitHub. repositório:

   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 usar a Próxima versão principal.

Quando terminar, o Xcode resolve as dependências do pacote e faz o download deles em segundo plano. Para mais detalhes sobre como adicionar pacotes dependências, consulte Artigo da Apple.

Faça o download e instale manualmente o SDK da PAL

Se não quiser usar o Swift Package Manager, faça o download do SDK da PAL e adicioná-lo manualmente ao projeto.

1. Faça o download e extraia o SDK da PAL para iOS.
2. Siga o Guia do desenvolvedor 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 o PALNonceLoader: O SDK da PAL exige que cada nova solicitação de fluxo seja acompanhada por um valor de uso único recém-gerado. No entanto, os valores de uso único podem ser reutilizados em vários no mesmo fluxo.

Todos os snippets de código abaixo são modificações 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 somente uma instância do 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. Parâmetro &correlator, inalterado durante a vida útil de uma página ou de um usuário do app.

Você ainda tem controle sobre o correlator de stream, ou &scor, que precisa ser é redefinida uma vez para cada nova transmissão. Todas as solicitações de anúncios do mesmo stream precisam compartilhar o mesmo valor de PALNonceLoader e de correlação de stream para o limite de frequência e recursos de exclusão competitiva para funcionar 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 '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 dela 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.
 *
 * 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 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 valores 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), defina seu valor de uso único como o valor no campo parâmetro givn. O valor de uso único é seguro para URLs: você não precisa codificá-lo para URL.

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

Por fim, você precisa adicionar métodos para processar o envio da sessão de reprodução de conteúdo informações e cliques no SDK. Confira o exemplo a seguir como implementar a 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 deve ser chamado no "player de vídeo" iniciar" quando a reprodução é iniciada pela primeira vez, em resposta a uma uma ação iniciada pelo usuário (reproduzir com um clique) ou uma ação iniciada pelo app (reprodução automática) sendPlaybackEnd precisa ser chamado quando a reprodução terminar, e sendAdClick precisa ser chamado. será chamado sempre que o espectador clicar 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 conclua as etapas a seguir, o parâmetro de valor de uso único será propagado do SDK da PAL, por meio dos servidores intermediários e depois para o Google Ad Manager. Isso permite a monetização com o Google Ad Manager.

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

Configure seu servidor de anúncios de terceiros para incluir o valor de uso único na variável ao Ad Manager. Veja um exemplo de 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 a Implementação do lado do servidor do Google Ad Manager guia.

O Ad Manager procura por givn= para identificar o valor de uso único. O anúncio de terceiros servidor precisa suportar algumas macros próprias, como %%custom_key_for_google_nonce%% e a substitua pelo parâmetro de consulta de valor de uso único. que você forneceu na etapa anterior. Mais informações sobre como fazer isso deve estar disponível na documentação do servidor de anúncios de terceiros.