Inizia

Prerequisiti

• Xcode 13 o superiore

Questa guida descrive come richiamare l'SDK PAL per ricevere un nonce e monitorare gli eventi di riproduzione. Per seguire la guida completa, scarica l'applicazione di esempio PAL per tvOS.

Aggiungi l'SDK PAL al progetto

Installa l'SDK PAL utilizzando Swift Package Manager

L'SDK della libreria di accesso programmatico supporta Swift Package Manager a partire dalla versione 2.5.3. Segui i passaggi riportati di seguito per importare il pacchetto Swift.

1. In Xcode, installa il pacchetto Swift dell'SDK IMA andando su File > Aggiungi pacchetti....

2. Nel prompt visualizzato, cerca il repository GitHub del pacchetto SDK IMA:

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

3. Seleziona la versione del pacchetto Swift SDK PAL che vuoi utilizzare. Per i nuovi progetti, consigliamo di utilizzare la versione principale fino alla prossima.

Al termine, Xcode risolve le dipendenze dei pacchetti e le scarica in background. Per maggiori dettagli su come aggiungere dipendenze dei pacchetti, consulta l'articolo di Apple.

Scarica e installa manualmente l'SDK PAL

Se non vuoi utilizzare Swift Package Manager, puoi scaricare l'SDK PAL e aggiungerlo manualmente al tuo progetto.

1. Scarica ed estrai l'SDK PAL per iOS.
2. Segui la Guida per gli sviluppatori Apple per incorporare il framework nel tuo progetto.

Genera un nonce

Un "nonce" è una singola stringa criptata generata dal PAL utilizzando PALNonceLoader. L'SDK PAL richiede che ogni nuova richiesta di stream sia accompagnata da un nonce appena generato. Tuttavia, i nonce possono essere riutilizzati per più richieste di annunci all'interno dello stesso stream.

Tutti gli snippet di codice riportati di seguito sono modifiche a ViewController.m nell'applicazione di esempio PAL tvOS.

Per richiedere un nonce, inizia importando la libreria PAL:

@import ProgrammaticAccessLibrary;

Nota: ti consigliamo di creare una sola istanza della classe PALNonceLoader per ogni sessione utente nella tua app, a meno che la tua app non abbia più pagine o costrutti equivalenti. In questo modo il correlatore di pagina, o il parametro &correlator, rimane invariato per tutta la durata di una pagina o della sessione di un utente dell'app.

Hai comunque il controllo sul correlatore di stream, o &scor, che deve essere reimpostato una volta per ogni nuovo stream. Tutte le richieste di annunci dello stesso stream devono condividere lo stesso PALNonceLoader e lo stesso valore di correlatore dello streaming affinché la quota limite e le funzionalità di esclusione competitiva funzionino correttamente.

Quindi, crea un'istanza di PALNonceLoader e aggiungi stub per i due metodi di delega:

@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 {
}

Quindi, avvia una richiesta nonce, compila le relative proprietà e utilizzala per inizializzare un gestore 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.
 */
- (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];
}

Infine, compila i delegati del caricatore nonce per registrare i nonce generati:

#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);
}

Quando effettui la chiamata VAST diretta (DVC), imposta il nonce come valore nel parametro givn. Il nonce è sicuro per gli URL, quindi non è necessario codificarlo come URL.

Attenzione: se in precedenza hai fornito un nonce utilizzando il parametro paln, ti consigliamo vivamente di eseguire la migrazione a givn e interrompere l'invio di paln. Se vengono inclusi entrambi i parametri, si tratta di un comportamento indefinito in merito al nonce utilizzato.

Infine, devi aggiungere metodi per gestire l'invio all'SDK delle informazioni sulla sessione di riproduzione dei contenuti e dei clic. Vedi l'esempio seguente di implementazione dei metodi 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];
}

Nella tua implementazione, sendPlaybackStart deve essere chiamato all'"avvio del video player" quando la riproduzione inizia per la prima volta, in risposta a un'azione avviata dall'utente (click-to-play) o a un'azione avviata dall'app (riproduzione automatica), sendPlaybackEnd al termine della riproduzione e sendAdClick ogni volta che lo spettatore fa clic su un annuncio.

(Facoltativo) Inviare indicatori Google Ad Manager tramite ad server di terze parti

Configura la richiesta dell'ad server di terze parti per Ad Manager. Dopo aver completato i seguenti passaggi, il parametro nonce viene propagato dall'SDK PAL, attraverso i server intermedi e poi a Google Ad Manager. Ciò consente una migliore monetizzazione tramite Google Ad Manager.

Nota: se utilizzi più soluzioni di terze parti, ad esempio un server SSAI di terze parti che chiama un altro ad server di terze parti, devi assicurarti che il nonce criptato dell'SDK PAL venga inoltrato a ciascuna terza parte.

Configura l'ad server di terze parti in modo da includere il nonce nella richiesta del server ad Ad Manager. Di seguito è riportato un esempio di tag annuncio configurato all'interno dell'ad server di terze parti:

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

Per ulteriori dettagli, consulta la Guida all'implementazione lato server di Google Ad Manager.

Ad Manager cerca givn= per identificare il valore nonce. L'ad server di terze parti deve supportare alcune macro, ad esempio %%custom_key_for_google_nonce%%, e sostituirle con il parametro di query nonce fornito nel passaggio precedente. Ulteriori informazioni su come eseguire questa operazione dovrebbero essere disponibili nella documentazione dell'ad server di terze parti.