Débutter

PAL vous permet d'envoyer des signaux d'annonces Google dans vos demandes d'annonces et pendant la lecture des annonces.

Ce guide explique comment ajouter le SDK Android PAL à votre application. Pour voir un exemple d'application qui utilise PAL pour générer un nonce, téléchargez l'exemple Android depuis GitHub.

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 :

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

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 que PAL génère à l'aide de la classe NonceLoader. PAL exige que chaque demande de flux soit accompagnée d'un nonce unique. Toutefois, vous pouvez réutiliser les nonces pour plusieurs demandes d'annonces dans le même flux. Pour générer un nonce à l'aide du SDK PAL, apportez les modifications suivantes pour importer et configurer PAL, et créez une fonction pour générer un nonce :

  1. Importez et configurez PAL en procédant comme suit :

    1. Importer des classes 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. Créez des variables privées pour stocker les instances NonceLoader et NonceManager :

      private NonceLoader nonceLoader;
private NonceManager nonceManager;
      MainActivity.java

    3. Initialisez votre instance NonceLoader avec une instance ConsentSettings dans la méthode 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

    Dans votre application, créez une instance de la classe NonceLoader pour chaque session utilisateur. Si votre application comporte plusieurs pages ou constructions équivalentes, créez une instance NonceLoader pour chaque page ou équivalent. En utilisant la même instance NonceLoader, vous conservez le corrélateur de page &correlator inchangé pendant toute la durée de vie d'une page ou de la session d'un utilisateur dans l'application. Vous gardez le contrôle sur le corrélateur de flux &scor, que vous devez réinitialiser pour chaque nouveau flux en générant un nouveau nonce.

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

  2. Générez 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

    Vous n'avez besoin que d'un seul nonce pour toutes les demandes d'annonces lors de la lecture d'un même flux. À des fins de test, appelez cette fonction lorsque vous cliquez sur un bouton de votre application de test. Les paramètres NonceRequest définis dans ce guide sont des exemples de paramètres. Définissez vos paramètres en fonction des caractéristiques de votre application.

    Cette fonction génère un nonce de manière asynchrone. Vous devez gérer les cas de réussite et d'échec de la requête de nonce. Une fois le gestionnaire de nonces disponible, récupérez la nonce avant d'envoyer une demande d'annonce à l'aide de la méthode nonceManager.getNonce().

Joindre 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 publicitaire avant d'envoyer vos demandes d'annonces :

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

Suivre les événements de lecture

Pour suivre les événements de lecture, vous devez configurer des gestionnaires d'événements afin d'envoyer des signaux d'annonces à 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

Voici quand appeler chaque fonction dans votre implémentation :

  • sendPlaybackStart() : début de votre session de lecture vidéo
  • sendPlaybackEnd() : lorsque votre session de lecture vidéo se termine
  • sendAdClick() : chaque fois que le spectateur clique sur une annonce
  • sendTouch() : à chaque interaction tactile avec le lecteur

À des fins de test, associez les méthodes du gestionnaire d'événements aux événements de clic sur les boutons. Dans une implémentation de production, configurez votre application pour que les événements du lecteur appellent les méthodes du gestionnaire d'événements.

(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 transférer la valeur nonce dans chaque demande d'annonce. L'exemple fourni est celui d'une URL de demande d'annonce avec le paramètre nonce inclus. Le paramètre nonce se propage du SDK PAL à Ad Manager, en passant par vos serveurs intermédiaires, ce qui permet une meilleure monétisation.

Configurez votre ad server tiers pour qu'il inclue le nonce dans la demande du serveur envoyée à Ad Manager. Voici un exemple de tag d'annonce configuré 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 du nonce. Le serveur publicitaire tiers doit prendre en charge sa propre macro, 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.