Inizia

Prerequisiti

• Xcode 13 o versioni successive

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

Aggiungere l'SDK PAL al progetto

Installare l'SDK PAL utilizzando Swift Package Manager

L'SDK Programmatic Access Library 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 a File > Add Packages… (File > Aggiungi pacchetti…).

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

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

3. Seleziona la versione del pacchetto Swift dell'SDK PAL che vuoi utilizzare. Per i nuovi progetti, ti consigliamo di utilizzare l'opzione Fino alla prossima versione principale.

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

Scaricare e installare 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 tvOS.
2. Segui la guida per gli sviluppatori Apple per incorporare il framework nel tuo progetto.

Generare un nonce

Un "nonce" è una singola stringa criptata generata da 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 annuncio all'interno dello stesso stream.

Tutti gli snippet di codice riportati di seguito sono modifiche apportate 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 l'app non abbia più pagine o costrutti equivalenti. In questo modo, il correlatore di pagina o il parametro &correlator rimane invariato per la durata di una pagina o della sessione dell'app di un utente.

Hai comunque il controllo del 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 valore di PALNonceLoader e di correlatore dello stream per il corretto funzionamento delle funzionalità di quota limite e esclusione competitiva.

Successivamente, crea un'istanza di PALNonceLoader e aggiungi stub per i due metodi delegati:

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

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.
 *
 * 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];
}

Infine, compila i delegati del caricatore di 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 del parametro givn. Il nonce è sicuro per l'URL, quindi non è necessario codificarlo.

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

Infine, devi aggiungere metodi per gestire l'invio di informazioni e clic sulla sessione di riproduzione dei contenuti all'SDK. Vedi l'esempio seguente che implementa i 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 viene avviata per la prima volta, in risposta a un'azione avviata dall'utente (click-to-play) o da un'azione avviata dall'app (riproduzione automatica), sendPlaybackEnd deve essere chiamato al termine della riproduzione e sendAdClick deve essere chiamato ogni volta che lo spettatore fa clic su un annuncio.

(Facoltativo) Inviare indicatori di 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 si propaga dall'SDK PAL, attraverso i server intermediari, fino 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 ogni terza parte.

Configura l'ad server di terze parti in modo che includa il nonce nella richiesta del server ad Ad Manager. Ecco 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 una propria macro, ad esempio %%custom_key_for_google_nonce%%, e sostituirla con il parametro di query nonce che hai fornito nel passaggio precedente. Maggiori informazioni su come eseguire questa operazione dovrebbero essere disponibili nella documentazione dell'ad server di terze parti.