Premiers pas

Conformément aux Règles de Google relatives au consentement de l'utilisateur dans l'UE, vous êtes tenu de divulguer certaines informations à vos utilisateurs situés dans l'Espace économique européen (EEE) et au Royaume-Uni, et d'obtenir leur consentement pour utiliser des cookies ou tout autre stockage local, lorsque la législation l'impose, et pour utiliser des données à caractère personnel (telles que l'identifiant publicitaire) pour diffuser des annonces. Ces règles reflètent les exigences de la directive vie privée et communications électroniques de l'UE, et celles du Règlement général sur la protection des données (RGPD).

Pour aider les éditeurs à satisfaire aux obligations qui leur sont imposées par ce règlement, Google propose le SDK UMP (User Messaging Platform). Le SDK UMP a été mis à jour pour être compatible avec les dernières normes de l'IAB. Toutes ces configurations peuvent désormais être gérées facilement dans la section AdMob Confidentialité et messages.

Prérequis

• Suivez le guide de démarrage.

• API Android niveau 21 ou supérieur (pour Android)

• Si vous travaillez sur des exigences liées au RGPD, consultezImpact des exigences de l'IAB sur les messages demandant le consentement des utilisateurs de l'UE

Créer un type de message

Créez des messages destinés aux utilisateurs avec l'un des types de messages disponibles dans l'onglet Confidentialité et messages de votre compte AdMob . Le SDK UMP tente d'afficher un message utilisateur créé à partir de l' AdMob ID application défini dans votre projet. Si aucun message n'est configuré pour votre application, le SDK renvoie une erreur.

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

Installer le SDK

1. Suivez la procédure d'installation du SDK C++ Google Mobile Ads (GMA). Le SDK UMP C++ est inclus dans le SDK GMA C++.

2. Avant de continuer, veillez à configurer l'ID AdMob de votre application dans le projet.

3. Dans votre code, initialisez le SDK UMP en appelant ConsentInfo::GetInstance().

   • Sur Android, vous devez transmettre les éléments JNIEnv et Activity fournis par le NDK. Cette opération n'est nécessaire que la première fois que vous appelez GetInstance().
   • Si vous utilisez déjà le SDK C++ Firebase dans votre application, vous pouvez transmettre un firebase::App la première fois que vous appelez GetInstance().

   #include "firebase/gma/ump.h"
   
   namespace ump = ::firebase::gma::ump;
   
   // Initialize using a firebase::App
   void InitializeUserMessagingPlatform(const firebase::App& app) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(app);
   }
   
   // Initialize without a firebase::App
   #ifdef ANDROID
   void InitializeUserMessagingPlatform(JNIEnv* jni_env, jobject activity) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(jni_env, activity);
   }
   #else  // non-Android
   void InitializeUserMessagingPlatform() {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
   }
   #endif
   

Les appels suivants à ConsentInfo::GetInstance() renvoient tous la même instance.

Remarque :Les méthodes GetInstance() comportent un paramètre de sortie firebase::InitResult facultatif, qui renvoie firebase::kInitResultSuccess si le SDK a bien été initialisé, ou firebase::kInitResultFailedMissingDependency s'il manque des dépendances requises dans votre application. Assurez-vous d'avoir suivi toutes les étapes d'installation de votre plate-forme si cette erreur se produit.

Si vous avez fini d'utiliser le SDK UMP, vous pouvez l'arrêter en supprimant l'instance ConsentInfo:

void ShutdownUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
  delete consent_info;
}

Remarque :Vous n'avez pas besoin d'initialiser le SDK C++ Google Mobile Ads avant d'initialiser le SDK User Messaging Platform.

Surveiller les opérations asynchrones à l'aide d'un Future

Un objet firebase::Future vous permet de déterminer l'état d'avancement des appels de méthode asynchrones.

Toutes les fonctions et tous les appels de méthode C++ UMP qui fonctionnent de manière asynchrone renvoient un Future et fournissent également une fonction "Dernier résultat" pour récupérer l'Future de la dernière opération.

Il existe deux façons d'obtenir un résultat à partir d'un Future:

1. Appelez OnCompletion() en transmettant votre propre fonction de rappel, qui est appelée à la fin de l'opération.
2. Vérifiez régulièrement le status() de Future. Lorsque l'état passe de kFutureStatusPending à kFutureStatusCompleted, l'opération est terminée.

Une fois l'opération asynchrone terminée, vous devez vérifier l'élément error() de Future pour obtenir le code d'erreur de l'opération. Si le code d'erreur est 0 (kConsentRequestSuccess ou kConsentFormSuccess), l'opération a bien été effectuée. Sinon, vérifiez le code d'erreur et error_message() pour déterminer le problème.

Remarque :Le code d'erreur renvoyé par RequestConsentInfoUpdate() utilise l'énumération ConsentRequestError. Toutes les autres opérations utilisent ConsentFormError.

Rappel de confirmation

Voici un exemple d'utilisation de OnCompletion pour définir un rappel de fin, appelé à la fin de l'opération asynchrone.

void MyApplicationStart() {
  // [... other app initialization code ...]

  ump::ConsentInfo *consent_info = ump::ConsentInfo::GetInstance();

  // See the section below for more information about RequestConsentInfoUpdate.
  firebase::Future<void> result = consent_info->RequestConsentInfoUpdate(...);

  result.OnCompletion([](const firebase::Future<void>& req_result) {
    if (req_result.error() == ump::kConsentRequestSuccess) {
      // Operation succeeded. You can now call LoadAndShowConsentFormIfRequired().
    } else {
      // Operation failed. Check req_result.error_message() for more information.
    }
  });
}

Mettre à jour l'interrogation en boucle

Dans cet exemple, après le lancement d'une opération asynchrone au lancement de l'application, les résultats sont vérifiés ailleurs, dans la fonction de mise à jour de la boucle du jeu (qui s'exécute une fois par frame).

ump::ConsentInfo *g_consent_info = nullptr;
bool g_waiting_for_request = false;

void MyApplicationStart() {
  // [... other app initialization code ...]

  g_consent_info = ump::ConsentInfo::GetInstance();
  // See the section below for more information about RequestConsentInfoUpdate.
  g_consent_info->RequestConsentInfoUpdate(...);
  g_waiting_for_request = true;
}

// Elsewhere, in the game's update loop, which runs once per frame:
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_waiting_for_request) {
    // Check whether RequestConsentInfoUpdate() has finished.
    // Calling "LastResult" returns the Future for the most recent operation.
    firebase::Future<void> result =
      g_consent_info->RequestConsentInfoUpdateLastResult();

    if (result.status() == firebase::kFutureStatusComplete) {
      g_waiting_for_request = false;
      if (result.error() == ump::kConsentRequestSuccess) {
        // Operation succeeded. You can call LoadAndShowConsentFormIfRequired().
      } else {
        // Operation failed. Check result.error_message() for more information.
      }
    }
  }
}

Pour en savoir plus sur firebase::Future, consultez la documentation du SDK Firebase C++ et la documentation du SDK GMA C++.

Remarque :Dans le SDK C++ UMP, toutes les opérations asynchrones renvoient firebase::Future<void>.

Demande d'informations sur le consentement

Vous devez demander la mise à jour des informations de consentement de l'utilisateur à chaque lancement d'application, à l'aide de RequestConsentInfoUpdate(). Cela détermine si l'utilisateur doit donner son consentement s'il ne l'a pas déjà fait ou s'il a expiré.

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct.
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age
  // of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [](const Future<void>& result) {
      if (result.error() != ump::kConsentRequestSuccess) {
        LogMessage("Error requesting consent update: %s", result.error_message());
      } else {
        // Consent status is now available.
      }
    });
}

Reportez-vous à la section ci-dessus pour voir un exemple de vérification de l'achèvement à l'aide d'une interrogation en boucle de mise à jour plutôt que d'un rappel d'achèvement.

Avertissement :Si vous utilisez d'autres moyens de vérifier l'état du consentement, tels que le cache de votre application ou une chaîne de consentement précédemment enregistrée, vous risquez d'obtenir une erreur TCF 3.3 si le consentement a expiré.

Charger et afficher un formulaire de consentement si nécessaire

Une fois que vous avez reçu l'état de consentement le plus récent, appelezLoadAndShowConsentFormIfRequired() sur la classeConsentInfo pour charger un formulaire de consentement. Si l'état de consentement est requis, le SDK charge un formulaire et l'affiche immédiatement à partir du FormParentfourni. La Future terminée après la fermeture du formulaire. Si le consentement n'est pas requis, la Future terminée immédiatement.

Remarque :Selon la plate-forme, FormParent il s'agit soit d'une référence JNI jobject à un Activity Android, soit d'un pointeur vers un UIViewController iOS, castez vers un type FormParent.

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      } else {
        consent_info->LoadAndShowConsentFormIfRequired(parent).OnCompletion(
        [*](const Future<void>& form_result) {
          if (form_result.error() != ump::kConsentFormSuccess) {
            // form_result.error() is a kConsentFormError enum.
            LogMessage("Error showing consent form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

Si vous devez effectuer des actions une fois que l'utilisateur a fait un choix ou ignoré le formulaire, placez cette logique dans le code qui gère le Future renvoyé par LoadAndShowConsentFormIfRequired().

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 ConsentInfo::GetInstance()‑>CanRequestAds(). Lorsque vous recueillez le consentement des utilisateurs, vous pouvez les vérifier à deux endroits:

1. Une fois le consentement obtenu dans la session en cours.
2. Immédiatement après avoir appelé RequestConsentInfoUpdate(). Il est possible que le consentement ait été obtenu au cours de la session précédente. Pour des raisons de latence, nous vous recommandons de ne pas attendre la fin du rappel afin de pouvoir commencer à charger des annonces dès que possible après le lancement de votre application.

Remarque: ConsentInfo::GetInstance()‑>CanRequestAds() renvoie toujours false tant que vous n'avez pas appelé RequestConsentInfoUpdate()

.

Si une erreur se produit pendant le processus de recueil du consentement, vous devez tout de même essayer de demander des annonces. Le SDK UMP utilise l'état de consentement de la session précédente.

L'exemple complet suivant utilise l'interrogation de boucles de mise à jour, mais vous pouvez également utiliser des rappels OnCompletion pour surveiller les opérations asynchrones. Utilisez la technique qui convient le mieux à votre structure de code.

#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/gma/ump.h"

namespace gma = ::firebase::gma;
namespace ump = ::firebase::gma::ump;
using firebase::Future;

ump::ConsentInfo* g_consent_info = nullptr;
// State variable for tracking the UMP consent flow.
enum { kStart, kRequest, kLoadAndShow, kInitGma, kFinished, kErrorState } g_state = kStart;
bool g_ads_allowed = false;

void MyApplicationStart() {
  g_consent_info = ump::ConsentInfo::GetInstance(...);

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  g_consent_info->RequestConsentInfoUpdate(params);
  // CanRequestAds() can return a cached value from a previous run immediately.
  g_ads_allowed = g_consent_info->CanRequestAds();
  g_state = kRequest;
}

// This function runs once per frame.
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_state == kRequest) {
    Future<void> req_result = g_consent_info->RequestConsentInfoUpdateLastResult();

    if (req_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (req_result.error() == ump::kConsentRequestSuccess) {
        // You must provide the FormParent (Android Activity or iOS UIViewController).
        ump::FormParent parent = GetMyFormParent();
        g_consent_info->LoadAndShowConsentFormIfRequired(parent);
        g_state = kLoadAndShow;
      } else {
        LogMessage("Error requesting consent status: %s", req_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kLoadAndShow) {
    Future<void> form_result = g_consent_info->LoadAndShowConsentFormIfRequiredLastResult();

    if (form_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (form_result.error() == ump::kConsentRequestSuccess) {
        if (g_ads_allowed) {
          // Initialize GMA. This is another asynchronous operation.
          firebase::gma::Initialize();
          g_state = kInitGma;
        } else {
          g_state = kFinished;
        }
        // Optional: shut down the UMP SDK to save memory.
        delete g_consent_info;
        g_consent_info = nullptr;
      } else {
        LogMessage("Error displaying consent form: %s", form_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kInitGma && g_ads_allowed) {
    Future<gma::AdapterInitializationStatus> gma_future = gma::InitializeLastResult();

    if (gma_future.status() == firebase::kFutureStatusComplete) {
      if (gma_future.error() == gma::kAdErrorCodeNone) {
        g_state = kFinished;
        // TODO: Request an ad.
      } else {
        LogMessage("Error initializing GMA: %s", gma_future.error_message());
        g_state = kErrorState;
      }
    }
  }
}

Options de confidentialité

Certains formulaires de consentement exigent que l'utilisateur modifie son consentement à tout moment. Si nécessaire, suivez les étapes ci-dessous pour implémenter un bouton d'options de confidentialité.

Pour cela, les opérations suivantes sont nécessaires :

1. Implémentez un élément d'interface utilisateur, tel qu'un bouton sur la page des paramètres de votre application, qui peut déclencher un formulaire d'options de confidentialité.
2. Une fois l'opération LoadAndShowConsentFormIfRequired() terminée, vérifiezgetPrivacyOptionsRequirementStatus() pour déterminer si l'élément d'interface utilisateur pouvant présenter le formulaire d'options de confidentialité doit être affiché.
3. Lorsqu'un utilisateur interagit avec votre élément d'interface utilisateur, appelezshowPrivacyOptionsForm() pour afficher le formulaire afin qu'il puisse mettre à jour ses options de confidentialité à tout moment.

Test

Si vous souhaitez tester l'intégration dans votre application au fur et à mesure du développement, suivez ces étapes pour enregistrer votre appareil de test de manière programmatique. Veillez à supprimer le code qui définit ces ID d'appareils de test avant de publier votre application.

1. Appelez le RequestConsentInfoUpdate().

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

   Android

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

   iOS

   <UMP SDK>To enable debug mode for this device,
   set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
   

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

4. Modifiez votre code pour définirConsentRequestParameters.debug_settings.debug_device_ids pour la liste de vos ID d'appareils de test.

   void MyApplicationStart() {
     ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);
   
     ump::ConsentRequestParameters params;
     params.tag_for_under_age_of_consent = false;
     params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
   
     consent_info->RequestConsentInfoUpdate(params);
   }
   

Forcer une zone géographique

Le SDK UMP permet de tester le comportement de votre application comme si l'appareil était situé dans l'EEE ou au Royaume-Uni à l'aide de ConsentRequestParameters.debug_settings.debug_geography. Notez que les paramètres de débogage ne fonctionnent que sur les appareils de test.

void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
  // Geography appears as EEA for debug devices.
  params.debug_settings.debug_geography = ump::kConsentDebugGeographyEEA

  consent_info->RequestConsentInfoUpdate(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() .

  ConsentInfo::GetInstance()->Reset();

Attention :Cette méthode est destinée à être utilisée à des fins de test uniquement. Vous ne devez pas appeler Reset() dans le code de production.