Começar

Pré-requisitos

  • Xcode 13 ou versões mais recentes.

Este guia descreve como invocar o SDK da PAL para receber um valor de uso único e monitorar eventos de reprodução. Para conferir um app de exemplo que usa a PAL para gerar um nonce, faça o download do exemplo do iOS no GitHub.

Adicionar o SDK da PAL ao seu projeto

Instalar o SDK da 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 da PAL acessando File > Add Packages....

  2. No prompt que aparece, pesquise o repositório do GitHub do pacote Swift do SDK da PAL:

    https://github.com/googleads/swift-package-manager-google-programmatic-access-library-ios
    
  3. Selecione a versão do pacote Swift do SDK da 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 da PAL

Se você não quiser usar o Swift Package Manager, baixe o SDK da PAL e adicione-o manualmente ao seu projeto.

  1. Baixe e extraia o SDK da PAL para iOS.
  2. Siga o Guia do desenvolvedor da Apple para incorporar o framework ao seu projeto.

Gerar um valor de uso único

Um "nonce" é uma única string criptografada gerada pelo PAL usando o PALNonceLoader. O SDK da PAL exige que cada novo fluxo seja acompanhado 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 do PAL para iOS.

Para solicitar um nonce, comece importando a biblioteca PAL:

@import ProgrammaticAccessLibrary;

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úncio do mesmo fluxo precisam compartilhar o mesmo PALNonceLoader e valor de correlator de fluxo 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 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 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 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;
  request.OMIDPartnerName = @"SamplePartner";
  request.OMIDPartnerVersion = @"6.2.1";

  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 os 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.

Se você estiver solicitando e renderizando anúncios do Google, será necessário renderizar o ícone e a sobreposição AdChoices. Para detalhes sobre como analisar a resposta VAST e renderizar ícones, consulte Ícone Opções de Anúncios e sobreposição.

Por fim, adicione métodos para processar o envio de 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 terceirizado para o Ad Manager. Depois de concluir as etapas a seguir, o parâmetro valor de uso único será propagado do SDK da PAL, pelos servidores intermediários e, em seguida, para o Google Ad Manager. Isso permite uma monetização melhor com o Google Ad Manager.

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 uso único. O servidor de anúncios de terceiros 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.