Commencer

La première étape consiste à ajouter le SDK Android PAL à votre application.

Ajouter le SDK PAL Android en tant que bibliothèque

À partir de la version 18.0.0, le SDK PAL est hébergé dans le dépôt Maven de Google et peut être ajouté à votre application comme suit:

app/build.gradle

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

Vous pouvez également télécharger le SDK PAL à partir du dépôt Maven de Google et l'ajouter manuellement à votre application.

Générer un nonce

Un "nonce" est une chaîne chiffrée unique générée par PAL à l'aide de NonceLoader. Le SDK PAL exige que chaque nouvelle requête de flux soit accompagnée d'un nonce nouvellement généré. Toutefois, les nonces peuvent être réutilisés pour plusieurs demandes d'annonces dans le même flux. Pour générer un nonce à l'aide du SDK PAL, modifiez MyActivity.java. Pour voir une application exemple qui utilise PAL pour générer un nonce, téléchargez l'exemple Android sur GitHub.

Vous devez d'abord importer le SDK PAL, créer des propriétés privées pour stocker vos NonceLoader et NonceManager, puis initialiser votre NonceLoader.

Nous vous recommandons de ne créer qu'une seule instance de la classe NonceLoader pour chaque session utilisateur dans votre application, sauf si votre application comporte plusieurs pages ou constructions équivalentes. Le corrélateur de page (&correlator) reste inchangé pendant toute la durée de vie d'une page ou d'une session utilisateur dans l'application. Vous pouvez toujours contrôler le corrélateur de flux (&scor), qui doit être réinitialisé une fois pour chaque nouveau flux.

Toutes les demandes d'annonces du même flux doivent partager la même valeur NonceLoader et de corrélateur de flux pour que les fonctionnalités de limitation de la fréquence d'exposition et d'exclusion réciproque fonctionnent correctement.

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

Ensuite, créez une fonction pour déclencher la génération de nonce. Vous n'avez besoin que d'un seul nonce pour toutes les demandes d'annonces d'une seule lecture en streaming. À des fins de test, vous pouvez appeler cette fonction lorsque vous cliquez sur un bouton dans votre application de test. Les paramètres NonceRequest définis ici sont des exemples de paramètres. Vous devez définir vos paramètres en fonction des caractéristiques de votre propre application.

Cette fonction déclenche la génération de nonce de manière asynchrone. Vous devez donc implémenter un AsyncTask pour gérer la réussite ou l'échec de la requête de 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());
  }
}

Une fois un gestionnaire de nonce créé, le nonce peut être récupéré à tout moment à l'aide de nonceManager.getNonce().

Associer un nonce à la demande d'annonce

Pour utiliser le nonce généré, ajoutez un paramètre givn et la valeur du nonce à votre tag d'annonce avant d'envoyer vos demandes d'annonces.

Important :Si vous avez déjà fourni un nonce à l'aide du paramètre paln, nous vous recommandons vivement de passer à givn et d'arrêter d'envoyer paln. Si les deux paramètres sont inclus, le comportement n'est pas défini concernant le nonce utilisé.

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

Suivre les événements de lecture

Enfin, vous devez implémenter divers gestionnaires d'événements pour votre lecteur. À des fins de test, vous pouvez les associer à des événements de clic sur un bouton, mais dans une implémentation réelle, ils seraient déclenchés par les événements de lecteur appropriés:

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

Voici quand appeler chaque fonction dans votre implémentation:

• sendPlaybackStart(): au début de votre session de lecture vidéo
• sendPlaybackEnd(): à la fin de votre session de lecture vidéo
• sendAdClick(): chaque fois que l'utilisateur clique sur une annonce
• sendTouch(): à chaque interaction tactile avec le lecteur

(Facultatif) Envoyer des signaux Google Ad Manager via des ad servers tiers

Lorsque vous configurez votre ad server tiers pour qu'il fonctionne avec Google Ad Manager, consultez la documentation de votre serveur pour capturer et transmettre la valeur nonce dans chaque demande d'annonce. L'exemple fourni est une URL de demande d'annonce avec le paramètre nonce inclus. Le paramètre nonce se propage à partir du SDK PAL, via vos serveurs intermédiaires, puis vers Ad Manager, ce qui permet une meilleure monétisation.

Remarque :Si vous utilisez plusieurs solutions tierces, par exemple un serveur SSAI tiers appelant un autre ad server tiers, vous devez vous assurer que le nonce chiffré du SDK PAL est transféré à chaque tiers.

Configurez votre ad server tiers pour qu'il inclue le nonce dans la requête du serveur envoyée à Ad Manager. Voici un exemple de balise d'annonce configurée dans l'ad server tiers:

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

Pour en savoir plus, consultez le guide d'implémentation côté serveur de Google Ad Manager.

Ad Manager recherche givn= pour identifier la valeur nonce. Le serveur publicitaire tiers doit prendre en charge une macro qui lui est propre, telle que %%custom_key_for_google_nonce%%, et la remplacer par le paramètre de requête nonce que vous avez fourni à l'étape précédente. Pour en savoir plus, consultez la documentation de l'ad server tiers.