Premiers pas

Le SDK Google User Messaging Platform (UMP) est un outil permettant vous aider à gérer vos paramètres de confidentialité. Pour en savoir plus, consultez À propos de l'outil Confidentialité et messagerie.

Prérequis

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

Créer un type de message

Créez des messages destinés aux utilisateurs avec l'une des Types de messages disponibles pour les utilisateurs dans la section Confidentialité l'onglet "Messages" de votre AdMob Google Cloud. Le SDK UMP tente d'afficher un message sur la confidentialité créé à partir de AdMob l'identifiant de l'application dans votre projet.

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

Installer le SDK

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

2. Veillez à configurer l'application AdMob de votre application ID dans le projet. avant de continuer.

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. Vous ne devez effectuer cette opération que la première fois que vous appelez GetInstance().
   • Si vous utilisez déjà le langage Firebase C++ SDK dans votre application, vous pouvez transmettre dans 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() ont un paramètre firebase::InitResult paramètre de sortie, qui renvoie firebase::kInitResultSuccess si le SDK était initialisé avec succès, ou firebase::kInitResultFailedMissingDependency si toutes les dépendances requises sont manquantes dans votre application. Assurez-vous d'avoir suivi toutes les étapes d'installation la procédure à suivre plate-forme si cette erreur se produit.

Si vous avez fini d'utiliser le SDK UMP, vous pouvez le fermer en supprimant le Instance ConsentInfo:

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

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

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

A firebase::Future permet de déterminer l'état d'avancement d'une méthode asynchrone appels.

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

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 lorsque l'opération terminé.
2. Vérifiez régulièrement les status() de Future. Lorsque état passe de kFutureStatusPending à kFutureStatusCompleted, la valeur est terminée.

Une fois l'opération asynchrone terminée, vous devez vérifier error() de Future pour obtenir l'erreur de l'opération. du code source. Si le code d'erreur est 0 (kConsentRequestSuccess ou kConsentFormSuccess), l'opération s'est terminée avec succès ; Sinon, vérifiez le code d'erreur et error_message() pour identifier le problème.

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

Rappel d'achèvement

Voici un exemple d'utilisation de OnCompletion pour définir un rappel d'achèvement. qui est 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 lors du lancement de l'application, les résultats sont vérifiés ailleurs, dans la fonction de boucle de mise à jour du jeu (qui exécute une fois par image).

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 plus d'informations sur firebase::Future, consultez la documentation sur le SDK Firebase C++ documentation et la documentation sur le SDK GMA C++.

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

Ajouter l'ID application

Vous trouverez l'ID de votre application dans le Interface utilisateur d'AdMob. Ajoutez la pièce d'identité à votre à l'aide de l'extrait de code suivant:

Demande d'informations sur le consentement

Vous devez demander la mise à jour des informations sur le consentement de l'utilisateur pour chaque application lancer à l'aide de RequestConsentInfoUpdate(). Cette demande vérifie les éléments suivants:

• Le consentement est-il requis ? Par exemple, le consentement est requis pour ou que la précédente décision de consentement a expiré.
• Indique si un point d'entrée pour les options de confidentialité est requis. Certains messages sur la confidentialité exiger que les applications autorisent les utilisateurs à modifier leurs options de confidentialité à tout moment.

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

Vous trouverez ci-dessus un exemple de vérification d'achèvement à l'aide de une interrogation en boucle de mise à jour plutôt qu'un rappel de fin.

Avertissement :En utilisant d'autres moyens de vérifier l'état du consentement, comme le cache de votre ou une chaîne de consentement précédemment enregistrée, peut entraîner une Erreur du TCF 3.3 si le consentement est est arrivé à expiration.

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

Une fois que vous avez reçu les toutes dernières informations concernant l'état de votre consentement, appelez LoadAndShowConsentFormIfRequired() pour charger les formulaires nécessaires recueillir le consentement des utilisateurs. Une fois le chargement terminé, les formulaires s'affichent immédiatement.

Remarque :Selon la plate-forme, FormParent est une référence JNI jobject à un Activity Android ou un pointeur vers un iOS UIViewController, cast 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 privacy message form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

Important :Si aucun formulaire de message sur la confidentialité n'exige de recueillir le consentement des utilisateurs au préalable aux demandes d'annonces, le rappel est immédiatement invoqué.

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

Options de confidentialité

Certains formulaires de message sur la confidentialité sont présentés à partir d'une interface qui permet aux utilisateurs de gérer leurs options de confidentialité à tout moment. Pour en savoir plus sur le message que voient vos utilisateurs dans les options de confidentialité point d'entrée, consultez Types de messages disponibles pour les utilisateurs

Pour implémenter un point d'entrée pour les options de confidentialité, procédez comme suit:

1. Vérifiez getPrivacyOptionsRequirementStatus().
2. Si un point d'entrée des options de confidentialité est ajoutez un élément d'interface utilisateur visible et interactif à votre application.
3. Déclenchez le formulaire des options de confidentialité à l'aide de showPrivacyOptionsForm()

L'exemple de code suivant illustre ces étapes:

Demander des annonces

Avant de demander des annonces dans votre application, vérifiez si vous avez obtenu le consentement des utilisateurs de l'utilisateur via ConsentInfo::GetInstance()‑>CanRequestAds(). Il y a deux endroits où vérifier le consentement des utilisateurs:

• 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. En tant que latence nous vous recommandons de ne pas attendre la fin du rappel commencer à charger des annonces dès que possible après le lancement de votre application.

Remarque: ConsentInfo::GetInstance()‑>CanRequestAds() renvoie toujours false jusqu'à ce que vous ayez appelé RequestConsentInfoUpdate()

Si une erreur se produit lors du processus de collecte du consentement, vous devez pour tenter de demander des annonces. Le SDK UMP utilise l'état de consentement de l'autorisation session.

L'exemple complet suivant utilise l'interrogation en boucle de mise à jour, mais vous pouvez également utiliser des rappels OnCompletion 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/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 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 le développement, suivez suivez ces étapes pour enregistrer votre appareil de test de manière programmatique. Veillez à supprimer le 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, affiche l'ID de votre appareil et explique 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 votre presse-papiers.

4. Modifiez votre code pour définir ConsentRequestParameters.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ées dans l'EEE ou au Royaume-Uni par le biais 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 le l'état du SDK afin de 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 uniquement à être utilisée à des fins de test. Toi ne doit pas appeler Reset() dans le code de production.

Exemples sur GitHub