Inizia

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

Aggiungi 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:22.0.0'
    ...
}

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

Genera nonce

Un "nonce" è una singola stringa criptata generata da PAL utilizzando il NonceLoader. 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. Per generare un nonce utilizzando l'SDK PAL, apporta modifiche a MyActivity.java. Per vedere un'app di esempio che utilizza PAL per generare un nonce, scarica l'esempio per Android da GitHub.

Devi prima importare l'SDK PAL, creare alcune proprietà private per memorizzare NonceLoader e NonceManager e poi 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 della pagina (&correlator) rimane invariato per tutta la durata di una pagina o della sessione di un utente nell'app. Mantieni comunque il controllo sul correlatore stream (&scor), che deve essere reimpostato una volta per ogni nuovo stream.

Per il corretto funzionamento delle funzionalità di quota limite ed esclusione competitiva, tutte le richieste di annunci dello stesso stream devono condividere lo stesso valore NonceLoader e lo stesso valore del correlatore dello stream.

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

A questo punto, crea una funzione per attivare la generazione di un nonce. È necessario un solo nonce per tutte le richieste di annunci in una singola riproduzione in streaming. Per scopi di test, puoi chiamare questa funzione quando fai clic su un pulsante nell'app di test. I parametri NonceRequest impostati qui sono parametri di esempio. Devi impostare i parametri in base alle caratteristiche della tua app.

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

public void generateNonceForAdRequest() {
  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();
  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 di nonce, il nonce può essere recuperato in qualsiasi momento utilizzando nonceManager.getNonce().

Allega il nonce alla richiesta di annuncio

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

/**
 * 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);
}

Monitorare gli eventi di riproduzione

Infine, devi implementare vari gestori eventi per il player. Per scopi di test, puoi associarli agli eventi di clic sui pulsanti, ma in un'implementazione reale verrebbero 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 è indicato quando chiamare ogni funzione nell'implementazione:

  • sendPlaybackStart(): quando inizia la 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 tocco con il player

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

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

Configura l'ad server di terze parti in modo da includere 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. Il server pubblicitario di terze parti deve supportare una propria macro, ad esempio%%custom_key_for_google_nonce%%, e sostituirla 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.