Premiers pas

Le SDK Google UMP (User Messaging Platform) est un outil de confidentialité et de messagerie qui vous aide à gérer les choix de confidentialité. Pour en savoir plus, consultez À propos de l'outil Confidentialité et messages.

Prérequis

• Niveau d'API Android 21 ou supérieur

Créer un type de message

Créez des messages destinés aux utilisateurs à l'aide de l'un des types de messages destinés aux utilisateurs disponibles dans l'onglet Confidentialité et messages de votre compte AdMob. Le SDK UMP tente d'afficher un message de confidentialité créé à partir de l'ID d'application AdMob défini dans votre projet.

Pour en savoir plus, consultez À propos de la confidentialité et des messages.

Installer avec Gradle

Ajoutez la dépendance du SDK Google User Messaging Platform au fichier Gradle au niveau de l'application de votre module (généralement app/build.gradle) :

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}

Après avoir apporté les modifications au fichier build.gradle de votre application, veillez à synchroniser votre projet avec les fichiers Gradle.

Ajouter l'ID application

Votre ID d'application figure dans l'interface utilisateur d'AdMob. Ajoutez l'ID à votre AndroidManifest.xml avec l'extrait de code suivant :

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

Obtenir le consentement

Pour recueillir le consentement, procédez comme suit :

1. Demandez les informations les plus récentes sur le consentement de l'utilisateur.
2. Chargez et présentez un formulaire de consentement, si nécessaire.

Demande d'informations sur le consentement

Vous devez demander la mise à jour des informations sur le consentement de l'utilisateur à chaque lancement de l'application, à l'aide de requestConsentInfoUpdate(). Cette requête vérifie les éléments suivants :

• Indique si le consentement est requis. Par exemple, le consentement est requis pour la première fois ou la décision de consentement précédente a expiré.
• Indique si un point d'entrée pour les options de confidentialité est requis. Certains messages de confidentialité exigent que les applications permettent aux utilisateurs de modifier leurs options de confidentialité à tout moment.

Charger et présenter un formulaire de message sur la confidentialité si nécessaire

Une fois que vous avez reçu l'état de consentement le plus récent, appelez loadAndShowConsentFormIfRequired() pour charger tous les formulaires nécessaires pour recueillir le consentement des utilisateurs. Une fois le chargement terminé, les formulaires s'affichent immédiatement.

Le code suivant montre comment demander les dernières informations sur le consentement de l'utilisateur. Si nécessaire, le code charge et présente un formulaire de message de confidentialité :

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity,
            formError -> {
              // Consent has been gathered.
              onConsentGatheringCompleteListener.consentGatheringComplete(formError);
            }),
    requestConsentError ->
        onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError));
GoogleMobileAdsConsentManager.java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
      // Consent has been gathered.
      onConsentGatheringCompleteListener.consentGatheringComplete(formError)
    }
  },
  { requestConsentError ->
    onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError)
  },
)
GoogleMobileAdsConsentManager.kt

Options de confidentialité

Certains formulaires de message de confidentialité sont présentés à partir d'un point d'entrée des options de confidentialité généré par l'éditeur, ce qui permet aux utilisateurs de gérer leurs options de confidentialité à tout moment. Pour en savoir plus sur le message que vos utilisateurs voient au niveau du point d'entrée des options de confidentialité, consultez la section Types de messages utilisateur disponibles.

Vérifier si un point d'entrée pour les options de confidentialité est requis

Après avoir appelé requestConsentInfoUpdate(), vérifiez getPrivacyOptionsRequirementStatus() pour déterminer si un point d'entrée des options de confidentialité est requis pour votre application :

/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
GoogleMobileAdsConsentManager.java

/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
GoogleMobileAdsConsentManager.kt

Ajouter un élément visible à votre application

Si un point d'entrée pour la confidentialité est requis, ajoutez à votre application un élément d'interface utilisateur visible et interactif qui présente le formulaire d'options de confidentialité. Si un point d'entrée de confidentialité n'est pas requis, configurez votre élément d'interface utilisateur pour qu'il ne soit pas visible ni interactif.

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}
MyActivity.java

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}
MainActivity.kt

Présenter le formulaire d'options de confidentialité

Lorsque l'utilisateur interagit avec votre élément, présentez le formulaire d'options de confidentialité :

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
GoogleMobileAdsConsentManager.java

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Demander des annonces

Avant de demander des annonces dans votre application, vérifiez si vous avez obtenu le consentement de l'utilisateur à l'aide de canRequestAds(). Il existe deux endroits où vérifier le consentement lors de la collecte :

• Une fois que le consentement a été obtenu lors de la session en cours.
• Immédiatement après avoir appelé requestConsentInfoUpdate(). Il est possible que le consentement ait été obtenu lors de la session précédente. Pour des raisons de latence, nous vous recommandons de ne pas attendre la fin du rappel. Vous pourrez ainsi commencer à charger des annonces dès que possible après le lancement de votre application.

Si une erreur se produit lors du processus de collecte du consentement, vous devez tout de même vérifier si vous pouvez demander des annonces. Le SDK UMP utilise l'état du consentement de la session précédente.

Le code suivant vérifie si vous pouvez demander des annonces pendant le processus de collecte du consentement :

googleMobileAdsConsentManager.gatherConsent(
    this,
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.w(
            TAG,
            String.format("%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (googleMobileAdsConsentManager.canRequestAds()) {
        initializeMobileAdsSdk();
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds()) {
  initializeMobileAdsSdk();
}

googleMobileAdsConsentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(TAG, "${error.errorCode}: ${error.message}")
  }

  if (googleMobileAdsConsentManager.canRequestAds) {
    initializeMobileAdsSdk()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds) {
  initializeMobileAdsSdk()
}

Le code suivant configure le SDK Google Mobile Ads une fois le consentement de l'utilisateur recueilli:

private void initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return;
  }
  new Thread(
          () -> {
            // Initialize the Google Mobile Ads SDK on a background thread.
            MobileAds.initialize(this, initializationStatus -> {});

            // Load an ad on the main thread.
            runOnUiThread(this::loadBanner);
          })
      .start();
}
MyActivity.java

private fun initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return
  }
  CoroutineScope(Dispatchers.IO).launch {
    // Initialize the Google Mobile Ads SDK on a background thread.
    MobileAds.initialize(this@MainActivity) {}

    runOnUiThread {
      // Load an ad on the main thread.
      loadBanner()
    }
  }
}
MainActivity.kt

Tests

Si vous souhaitez tester l'intégration dans votre application au cours du développement, procédez comme suit pour enregistrer votre appareil de test de manière automatisée. Veillez à supprimer le code qui définit ces ID d'appareils de test avant de publier votre application.

1. Appelez requestConsentInfoUpdate().

2. Recherchez dans la sortie du journal un message semblable à l'exemple suivant, qui indique votre ID d'appareil et comment l'ajouter en tant qu'appareil de test :

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
   

3. Copiez l'ID de votre appareil de test dans votre presse-papiers.

4. Modifiez votre code pour appeler ConsentDebugSettings.Builder().TestDeviceHashedIds et transmettre une liste d'ID d'appareils de test.

   Java

   ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build();
   
   ConsentRequestParameters params = new ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build();
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this);
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   );
   

   Kotlin

   val debugSettings = ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build()
   
   val params = ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build()
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this)
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   )
   

Forcer une zone géographique

Le SDK UMP permet de tester le comportement de votre application comme si l'appareil se trouvait dans différentes régions, telles que l'EEE ou le Royaume-Uni, à l'aide de setDebugGeography(). Notez que les paramètres de débogage ne fonctionnent que sur les appareils de test.

ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
);

val debugSettings = ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
)

Réinitialiser l'état du consentement

Lorsque vous testez votre application avec le SDK UMP, il peut être utile de réinitialiser l'état du SDK afin de pouvoir simuler la première expérience d'installation d'un utilisateur. Pour ce faire, le SDK fournit la méthode reset().

consentInformation.reset();

consentInformation.reset()

Exemples sur GitHub

Pour voir un exemple complet de l'intégration du SDK UMP abordée sur cette page, consultez Java BannerExample et Kotlin BannerExample.