Commencer

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

Ajouter le SDK Android PAL 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:20.2.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 nécessite que chaque nouvelle requête de flux soit accompagnée d'un nonce nouvellement généré. Cependant, 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 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 celle-ci comporte plusieurs pages ou des constructions équivalentes. Ainsi, le corrélateur de page (&correlator) reste 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), qui doit être réinitialisé une fois pour chaque nouveau flux.

Toutes les demandes d'annonces d'un même flux doivent partager la même valeur NonceLoader et la même valeur 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);
    ...
  }

Créez ensuite 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 dans une lecture de flux unique. À des fins de test, vous pouvez appeler cette fonction lorsque vous cliquez sur un bouton dans votre application de test.

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

Une fois qu'un gestionnaire de nonce est créé, vous pouvez le récupérer à 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 nonce à votre tag d'emplacement publicitaire avant d'envoyer vos demandes d'annonces.

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

/**
 * 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 différents gestionnaires d'événements pour votre lecteur. À des fins de test, vous pouvez les joindre aux événements de clic sur un bouton, mais dans une implémentation réelle, ils seraient déclenchés par les événements appropriés du lecteur:

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 de votre implémentation:

• sendPlaybackStart(): début de la lecture de la vidéo
• sendPlaybackEnd(): lorsque la lecture de la vidéo se termine
• sendAdClick(): chaque fois que l'utilisateur clique sur une annonce.
• sendTouch(): lors de 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, reportez-vous à la documentation de votre serveur pour capturer et transférer 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 du SDK PAL vers 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 transmis à chaque tiers.

Configurez votre ad server tiers pour inclure le nonce dans la requête du serveur adressée à Ad Manager. Voici un exemple de tag d'emplacement publicitaire 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 nonce. L'ad server 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 sur la procédure à suivre, consultez la documentation de l'ad server tiers.