Inizia

Il primo passaggio consiste nell'aggiungere l'SDK Android PAL alla tua app.

Aggiungere l'SDK Android PAL 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:

app/build.gradle

...
dependencies {
    implementation 'com.google.android.gms:play-services-pal:20.2.0'
    ...
}

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 dal PAL utilizzando l'elemento NonceLoader. L'SDK PAL richiede che ogni nuova richiesta di flusso sia accompagnata da un nonce appena generato. Tuttavia, i nonce possono essere riutilizzati per più richieste di annunci all'interno dello stesso stream. Per generare un nonce utilizzando l'SDK PAL, apporta modifiche a MyActivity.java. Per visualizzare un'app di esempio che utilizza PAL per generare un nonce, scarica l'esempio per Android da GitHub.

Per prima cosa, devi importare l'SDK PAL, creare alcune proprietà private per archiviare NonceLoader e NonceManager, quindi inizializzare NonceLoader.

Ti consigliamo di creare una sola istanza della classe NonceLoader 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 (&correlator) rimane invariato per tutta la durata di una pagina o della sessione di un utente nell'app. Hai comunque il controllo sul correlatore stream (&scor), che deve essere reimpostato una volta per ogni nuovo stream.

Tutte le richieste di annunci dello stesso stream devono condividere lo stesso valore NonceLoader e correlatore dello streaming affinché la quota limite e le funzionalità di esclusione competitiva funzionino correttamente.

import android.app.Activity;
import android.os.Bundle;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;

import java.util.HashSet;
import java.util.Set;

public class MainActivity extends Activity {
...
  private NonceLoader nonceLoader;
  private NonceManager nonceManager = null;
  private ConsentSettings consentSettings;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // 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 isConsentToStorage = getConsentToStorage();

    videoView = findViewById(R.id.video_view);
    videoView.setOnTouchListener(this::onVideoViewTouch);

    consentSettings = ConsentSettings.builder()
            .allowStorage(isConsentToStorage)
            .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);
    ...
  }

Quindi, crea una funzione per attivare la generazione del nonce. Ti basta un solo nonce per tutte le richieste di annunci in un'unica riproduzione in streaming. A scopo di test, puoi chiamare questa funzione quando fai clic su un pulsante nell'app di test.

Questa funzione attiva la generazione di nonce in modo asincrono, quindi devi implementare un AsyncTask per gestire l'esito positivo o negativo della richiesta nonce:

public void generateNonceForAdRequest() {
  Set supportedApiFrameWorksSet = new HashSet();
  supportedApiFrameWorksSet.add(2);
  supportedApiFrameWorksSet.add(7);
  supportedApiFrameWorksSet.add(9);

  NonceRequest nonceRequest = NonceRequest.builder()
      .descriptionURL("https://example.com/content1")
      .iconsSupported(true)
      .omidVersion("1.0.0")
      .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(true)
      .build();
  NonceCallbackImpl callback = new NonceCallbackImpl();
  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(callback)
      .addOnFailureListener(callback);
}

private class NonceCallbackImpl implements OnSuccessListener<NonceManager>, OnFailureListener {
  @Override
  public void onSuccess(NonceManager manager) {
    nonceManager = manager;
    String nonceString = manager.getNonce();
    Log.i("PALSample", "Generated nonce: " + nonceString);
    // from here you would trigger your ad request and move on to initialize content
  }

  @Override
  public void onFailure(Exception error) {
    Log.e("PALSample", "Nonce generation failed: " + error.getMessage());
  }
}

Una volta creato un gestore nonce, il nonce può essere recuperato in qualsiasi momento utilizzando nonceManager.getNonce().

Allega un nonce alla richiesta di annuncio

Per utilizzare il nonce generato, aggiungi il tag annuncio con un parametro givn e il valore nonce prima di effettuare richieste di annunci.

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.

/**
 * The ad tag for your ad request, for example:
 * https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external\
 * /single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1\
 * &cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=
 *
 * For more sample ad tags, see
 * developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
 */
private static final String DEFAULT_AD_TAG = "Your ad tag";
...
@Override
public void onSuccess(NonceManager manager) {
  nonceManager = manager;
  String nonceString = manager.getNonce();
  Log.i("PALSample", "Generated nonce: " + nonceString);
  // Append the nonce to the ad tag URL.
  makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
}

Traccia eventi di riproduzione

Infine, dovrai implementare vari gestori di eventi per il tuo player. A scopo di test, puoi collegarli agli eventi di clic sui pulsanti, ma in un'implementazione reale verranno attivati dagli eventi del player appropriati:

public void sendAdClick() {
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

public void sendPlaybackStart() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

public void sendPlaybackEnd() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendTouch(e);
  }
}

Di seguito viene illustrato quando richiamare ogni funzione dell'implementazione:

• sendPlaybackStart(): l'inizio della sessione di riproduzione del video
• sendPlaybackEnd(): al termine della sessione di riproduzione del video
• sendAdClick(): ogni volta che lo spettatore fa clic su un annuncio.
• sendTouch(): a ogni interazione con il player tramite tocco

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

Quando configuri l'ad server di terze parti in modo che funzioni con Google Ad Manager, fai riferimento alla documentazione del server per acquisire e inoltrare il valore nonce in ogni richiesta di annuncio. L'esempio fornito è di un URL di 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 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.