Inizia

PAL ti consente di inviare indicatori degli annunci Google nelle tue richieste di annuncio e durante la riproduzione degli annunci.

Questa guida illustra come aggiungere l'SDK PAL per Android alla tua app. Per visualizzare un'app di esempio che utilizza PAL per generare un nonce, scarica l'esempio per Android da GitHub.

Aggiungi l'SDK PAL per Android come libreria

A partire dalla versione 18.0.0, l'SDK PAL è ospitato nel repository Maven di Google e può essere aggiunto alla tua app nel seguente modo:

implementation 'com.google.android.gms:play-services-pal:22.1.0'
build.gradle

In alternativa, l'SDK PAL può essere scaricato dal repository Maven di Google e aggiunto manualmente alla tua app.

Genera nonce

Un nonce è una singola stringa criptata generata da PAL utilizzando la classe NonceLoader. PAL richiede che ogni richiesta di stream sia accompagnata da un nonce univoco. Tuttavia, puoi riutilizzare i nonce per più richieste di annuncio nello stesso stream. Per generare un nonce utilizzando l'SDK PAL, apporta le seguenti modifiche per importare e configurare PAL e crea una funzione per generare un nonce:

1. Importa e configura PAL nel seguente modo:

   1. Importa corsi PAL:

      import com.google.ads.interactivemedia.pal.ConsentSettings;
      import com.google.ads.interactivemedia.pal.NonceLoader;
      import com.google.ads.interactivemedia.pal.NonceManager;
      import com.google.ads.interactivemedia.pal.NonceRequest;
      import com.google.android.gms.tasks.OnFailureListener;
      import com.google.android.gms.tasks.OnSuccessListener;
      import java.util.HashSet;
      import java.util.Set;
      MainActivity.java
      

   2. Crea variabili private per archiviare le istanze NonceLoader e NonceManager:

      private NonceLoader nonceLoader;
      private NonceManager nonceManager;
      MainActivity.java
      

   3. Inizializza l'istanza NonceLoader con un'istanza ConsentSettings nel metodo onCreate:

      @Override
      protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
      
        // The default value for allowStorage() is false, but can be
        // changed once the appropriate consent has been gathered. The
        // getConsentToStorage() method is a placeholder for the publisher's own
        // method of obtaining user consent, either by integrating with a CMP or
        // based on other methods the publisher chooses to handle storage consent.
        boolean isStorageAllowed = getConsentToStorage();
      
        ConsentSettings consentSettings =
            ConsentSettings.builder().allowStorage(isStorageAllowed).build();
      
        // It is important to instantiate the NonceLoader as early as possible to
        // allow it to initialize and preload data for a faster experience when
        // loading the NonceManager. A new NonceLoader will need to be instantiated
        // if the ConsentSettings change for the user.
        nonceLoader = new NonceLoader(this, consentSettings);
      
        adClickButton = findViewById(R.id.send_click_button);
      
        logView = findViewById(R.id.log_view);
        logView.setMovementMethod(new ScrollingMovementMethod());
      }
      MainActivity.java
      

   Nella tua app, crea un'istanza della classe NonceLoader per ogni sessione utente. Se la tua app ha più pagine o costrutti equivalenti, crea una nuova istanza NonceLoader per ogni pagina o equivalente. Utilizzando la stessa istanza di NonceLoader, il correlatore di pagina &correlator rimane invariato per la durata di una pagina o della sessione di un utente nell'app. Hai comunque il controllo sul correlatore di stream &scor, che devi reimpostare per ogni nuovo stream generando un nuovo nonce.

   Tutte le richieste di annunci dello stesso stream devono condividere la stessa istanza NonceLoader e lo stesso valore di correlatore dello stream per l'applicazione delle funzionalità di quota limite e di esclusione competitiva.

2. Genera un nonce:

   public void generateNonceForAdRequest(View view) {
     logMessage("Generate Nonce Request");
     Set supportedApiFrameWorksSet = new HashSet();
     // The values 2, 7, and 9 correspond to player support for VPAID 2.0,
     // OMID 1.0, and SIMID 1.1.
     supportedApiFrameWorksSet.add(2);
     supportedApiFrameWorksSet.add(7);
     supportedApiFrameWorksSet.add(9);
   
     NonceRequest nonceRequest =
         NonceRequest.builder()
             .descriptionURL("https://example.com/content1")
             .iconsSupported(true)
             .omidPartnerVersion("6.2.1")
             .omidPartnerName("Example Publisher")
             .playerType("ExamplePlayerType")
             .playerVersion("1.0.0")
             .ppid("testPpid")
             .sessionId("Sample SID")
             .supportedApiFrameworks(supportedApiFrameWorksSet)
             .videoPlayerHeight(480)
             .videoPlayerWidth(640)
             .willAdAutoPlay(true)
             .willAdPlayMuted(false)
             .build();
   
     nonceLoader
         .loadNonceManager(nonceRequest)
         .addOnSuccessListener(
             new OnSuccessListener<NonceManager>() {
               @Override
               public void onSuccess(NonceManager manager) {
                 nonceManager = manager;
                 String nonceString = manager.getNonce();
                 logMessage("Nonce generated");
                 logMessage(nonceString.substring(0, 20) + "...");
                 Log.i(LOG_TAG, "Generated nonce: " + nonceString);
   
                 // From here you would trigger your ad request and move on to initialize content.
                 exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
   
                 adClickButton.setEnabled(true);
               }
             })
         .addOnFailureListener(
             new OnFailureListener() {
               @Override
               public void onFailure(Exception error) {
                 logMessage("Nonce generation failed");
                 Log.e(LOG_TAG, "Nonce generation failed: " + error.getMessage());
               }
             });
   }
   MainActivity.java
   

   Ti serve un solo nonce per tutte le richieste di annunci in una singola riproduzione dello stream. A scopo di test, chiama questa funzione quando fai clic su un pulsante nell'app di test. I parametri NonceRequest impostati in questa guida sono parametri di esempio. Imposta i parametri in base alle caratteristiche della tua app.

   Questa funzione genera un nonce in modo asincrono. Devi gestire sia i casi di successo che quelli di errore della richiesta nonce. Una volta disponibile il gestore nonce, recupera il nonce prima di effettuare una richiesta di annuncio utilizzando il metodo nonceManager.getNonce().

Allegare il nonce alla richiesta di annuncio

Per utilizzare il nonce generato, aggiungi il parametro givn e il valore nonce al tag annuncio prima di effettuare le richieste di annuncio:

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.

// From here you would trigger your ad request and move on to initialize content.
exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
MainActivity.java

Monitorare gli eventi di riproduzione

Per monitorare gli eventi di riproduzione, devi configurare i gestori di eventi per inviare indicatori pubblicitari a Google:

// Triggered when a user clicks-through on an ad which was requested using a PAL nonce.
public void sendAdClick(View view) {
  logMessage("Ad click sent");
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

// In a typical PAL app, this is called when a user touch or click is detected,
// on the ad other than an ad click-through.
public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendAdTouch(e);
  }
}

// In a typical PAL app, this is called when a content playback session starts.
public void sendPlaybackStart() {
  logMessage("Playback start");
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

// In a typical PAL app, this is called when a content playback session ends.
public void sendPlaybackEnd() {
  logMessage("Playback end");
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}
MainActivity.java

Ecco quando chiamare ogni funzione nell'implementazione:

• sendPlaybackStart(): all'inizio della sessione di riproduzione del video
• sendPlaybackEnd(): Al termine della sessione di riproduzione video
• sendAdClick(): Ogni volta che lo spettatore fa clic su un annuncio
• sendTouch(): A ogni interazione touch con il player

A scopo di test, collega i metodi del gestore di eventi agli eventi di clic sui pulsanti. In un'implementazione di produzione, configura la tua app per gli eventi del giocatore in modo da chiamare i metodi del gestore di eventi.

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

Quando configuri l'ad server di terze parti per funzionare con Google Ad Manager, consulta la documentazione del server per acquisire e inoltrare il valore nonce in ogni richiesta di annuncio. L'esempio fornito è di un URL richiesta di annuncio con il parametro nonce incluso. Il parametro nonce si propaga dall'SDK PAL, attraverso i server intermedi e poi ad Ad Manager, consentendo una migliore monetizzazione.

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. Per ulteriori informazioni su come eseguire questa operazione, consulta la documentazione dell'ad server di terze parti.