Premiers pas

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

Prérequis

Niveau d'API Android 21 ou supérieur (pour Android)

Créer un type de message

Créez des messages utilisateur avec l'un des types de messages utilisateur disponibles sous 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 Confidentialité et messages.

Installer le SDK

Suivez les étapes pour installer le SDK Firebase C++. Le SDK UMP C++ est inclus dans le SDK Firebase C++.
Avant de continuer, assurez-vous de configurer l'ID d'application AdMob de votre application dans le projet .

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

Sur Android, vous devez transmettre le JNIEnv et l'Activity fournis par le NDK. Vous n'aurez besoin de le faire que la première fois que vous appellerez GetInstance().
Vous pouvez également transmettre un firebase::App la première fois que vous appelez GetInstance() si vous utilisez déjà le SDK Firebase C++ dans votre application.

#include "firebase/ump/ump.h"

namespace ump = ::firebase::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 ultérieurs à ConsentInfo::GetInstance() renvoient tous la même instance.

Si vous avez terminé 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;
}

Utiliser un `Future` pour surveiller les opérations asynchrones

A firebase::Future vous permet de déterminer l'état d'achèvement des appels de méthode asynchrones.

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

Vous pouvez obtenir un résultat à partir d'un Future de deux manières :

Appelez OnCompletion(), en transmettant votre propre fonction de rappel, qui est appelée lorsque l'opération est terminée.
Vérifiez régulièrement le status() du 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'error() du Future pour obtenir le code d'erreur de l'opération. Si le code d'erreur est 0 (kConsentRequestSuccess ou kConsentFormSuccess), l'opération s'est terminée correctement. Sinon, vérifiez le code d'erreur et error_message() pour déterminer ce qui s'est mal passé.

Rappel d'achèvement

Voici un exemple d'utilisation de OnCompletion pour définir un rappel d'achèvement, qui est appelé lorsque l'opération asynchrone est terminée.

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

Interrogation de la boucle de mise à jour

Dans cet exemple, une fois qu'une opération asynchrone est lancée au démarrage de l'application, les résultats sont vérifiés ailleurs, dans la fonction de boucle de mise à jour 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++.

Obtenir les informations de consentement de l'utilisateur

Vous devez demander une mise à jour des informations de consentement de l'utilisateur à chaque lancement de l'application, à l'aide de RequestConsentInfoUpdate(). Cette requête vérifie les points suivants :

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é.
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.

#include "firebase/ump/ump.h"

namespace ump = ::firebase::ump;

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());
      }
      // Consent information is successfully updated.
    });
}

Charger et présenter le formulaire de message de confidentialité

Une fois que vous avez reçu l'état de consentement le plus récent, appelez LoadAndShowConsentFormIfRequired() pour charger tous les formulaires requis pour recueillir le consentement de l'utilisateur. Une fois chargés, les formulaires s'affichent immédiatement.

#include "firebase/ump/ump.h"

namespace ump = ::firebase::ump;

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 privacy message form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

Voir ci-dessus un exemple de vérification de l'achèvement à l'aide de l' interrogation de la boucle de mise à jour plutôt que d'un rappel d'achèvement.

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

Options de confidentialité

Certains formulaires de message de confidentialité sont présentés à partir d'un point d'entrée des options de confidentialité rendu 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 point d'entrée des options de confidentialité, consultez Types de messages utilisateur disponibles.

Demander des annonces avec le consentement de l'utilisateur

Avant de demander des annonces, utilisez ConsentInfo::GetInstance()‑> CanRequestAds() pour vérifier si vous avez obtenu le consentement de l'utilisateur :

Voici les endroits où vous pouvez vérifier si vous pouvez demander des annonces tout en recueillant le consentement :

Une fois que le SDK UMP a recueilli le consentement lors de la session en cours.
Immédiatement après avoir appelé RequestConsentInfoUpdate(). Le SDK UMP peut avoir obtenu le consentement lors de la session d'application précédente.

Si une erreur se produit lors du processus de collecte du consentement, vérifiez si vous pouvez demander des annonces. Le SDK UMP utilise l'état de consentement de la session d'application précédente.

Éviter les demandes d'annonces redondantes

Lorsque vous vérifiez ConsentInfo::GetInstance()‑> CanRequestAds() après avoir recueilli le consentement et après avoir appelé RequestConsentInfoUpdate(), assurez-vous que votre logique empêche les demandes d'annonces redondantes qui pourraient entraîner le renvoi de true par les deux vérifications. Par exemple, avec une variable booléenne.

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

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

namespace gma = ::firebase::gma;
namespace ump = ::firebase::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 privacy message 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;
      }
    }
  }
}

Tests

Si vous souhaitez tester l'intégration dans votre application pendant son développement, suivez ces étapes pour enregistrer votre appareil de test par programmation. Veillez à supprimer le code qui définit ces ID d'appareils de test avant de publier votre application.

Appelez RequestConsentInfoUpdate().

Dans la sortie du journal, recherchez 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]

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

Modifiez votre code pour définir ConsentRequestParameters.debug_settings.debug_device_ids sur une liste des ID de vos 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 vous permet de tester le comportement de votre application comme si l'appareil était situé dans différentes régions, telles que l'Espace économique européen (EEE), le Royaume-Uni et la Suisse, à l'aide de 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 simuler la première installation par un utilisateur. Le SDK fournit la méthode Reset() pour ce faire.

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