Per iniziare

L'SDK Google User Messaging Platform (UMP) è uno strumento per la privacy e i messaggi che ti aiuta a gestire le scelte relative alla privacy. Per saperne di più, consulta Informazioni su Privacy e messaggi.

Prerequisiti

• Livello API Android 21 o superiore (per Android)

Creare un tipo di messaggio

Crea i messaggi per gli utenti con uno dei tipi di messaggi per gli utenti disponibili nella scheda Privacy e messaggi del tuo account AdMob. L'SDK UMP tenta di visualizzare un messaggio sulla privacy creato dall'ID applicazione AdMob impostato nel progetto.

Per ulteriori dettagli, consulta Informazioni su privacy e messaggi.

Installa l'SDK

1. Segui i passaggi per installare l'SDK Google Mobile Ads (GMA) per C++. L'SDK UMP per C++ è incluso nell'SDK GMA per C++.

2. Prima di continuare, assicurati di configurare l'ID app AdMob della tua app nel progetto.

3. Nel codice, inizializza l'SDK UMP chiamando ConsentInfo::GetInstance().

   • Su Android, devi superare i JNIEnv e i Activity forniti dall'NDK. Dovrai eseguire questa operazione solo la prima volta che chiami GetInstance().
   • In alternativa, se utilizzi già l'SDK Firebase C++ nella tua app, puoi passare un firebase::App la prima volta che chiami 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
   

Le chiamate successive a ConsentInfo::GetInstance() restituiscono tutte la stessa istanza.

Se hai finito di utilizzare l'SDK UMP, puoi arrestare l'SDK eliminando l'istanza ConsentInfo:

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

Utilizza un Future per monitorare le operazioni asincrone

Un firebase::Future ti consente di determinare lo stato di completamento delle chiamate di metodi asincroni.

Tutte le funzioni e le chiamate di metodo UMP C++ che operano in modo asincrono restituiscono un Future e forniscono anche una funzione "ultimo risultato" per recuperare il Future dall'operazione più recente.

Esistono due modi per ottenere un risultato da un Future:

1. Richiama OnCompletion(), inserendo la tua funzione di callback, che viene chiamata al completamento dell'operazione.
2. Controlla periodicamente il valore status() di Future. Quando lo stato passa da kFutureStatusPending a kFutureStatusCompleted, l'operazione è stata completata.

Al termine dell'operazione asincrona, devi controllare il error() di Future per ottenere il codice errore dell'operazione. Se il codice di errore è 0 (kConsentRequestSuccess o kConsentFormSuccess), l'operazione è stata completata correttamente. In caso contrario, controlla il codice di errore e error_message() per determinare cosa non va.

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

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

Per saperne di più su firebase::Future, consulta la documentazione dell'SDK Firebase C++ e la documentazione dell'SDK GMA C++.

Raccogliere il consenso

Per raccogliere il consenso, completa i seguenti passaggi:

1. Richiedi le informazioni più recenti sul consenso dell'utente.
2. Carica e presenta un modulo di consenso, se necessario.

Richiesta di informazioni sul consenso

Devi richiedere un aggiornamento delle informazioni sul consenso dell'utente a ogni avvio dell'app utilizzando RequestConsentInfoUpdate(). Questa richiesta controlla quanto segue:

• Se il consenso è obbligatorio. Ad esempio, il consenso è richiesto la prima volta o la decisione precedente sul consenso è scaduta.
• Se è richiesto un punto di accesso alle opzioni sulla privacy. Alcuni messaggi sulla privacy richiedono alle app di consentire agli utenti di modificare le loro opzioni sulla privacy in qualsiasi momento.

Carica e presenta un modulo per il messaggio sulla privacy, se necessario

Dopo aver ricevuto lo stato del consenso più aggiornato, chiama LoadAndShowConsentFormIfRequired() per caricare i moduli richiesti per raccogliere il consenso degli utenti. Dopo il caricamento, i moduli vengono visualizzati immediatamente.

Il seguente codice mostra come richiedere le informazioni più recenti sul consenso dell'utente. Se necessario, il codice viene caricato e presenta un modulo di messaggio sulla privacy:

#include "firebase/gma/ump.h"

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

Consulta sopra per un esempio di verifica del completamento mediante il polling del loop di aggiornamento anziché un callback di completamento.

Se devi eseguire azioni dopo che l'utente ha effettuato una scelta o chiuso il modulo, inserisci questa logica nel codice che gestisce il valore Future fornito da LoadAndShowConsentFormIfRequired().

Opzioni di privacy

Alcuni moduli di messaggi sulla privacy vengono presentati da un punto di accesso alle opzioni di privacy visualizzate dall'editore, che consente agli utenti di gestire le proprie opzioni di privacy in qualsiasi momento. Per scoprire di più sul messaggio visualizzato dagli utenti nel punto di accesso alle opzioni della privacy, consulta Tipi di messaggi per gli utenti disponibili.

Richiedi annunci

Prima di richiedere gli annunci nella tua app, controlla se hai ottenuto il consenso dell'utente utilizzando ConsentInfo::GetInstance()‑> CanRequestAds(). Esistono due punti da controllare durante la raccolta del consenso:

• Dopo che il consenso è stato raccolto nella sessione corrente.
• Subito dopo aver chiamato RequestConsentInfoUpdate(). È possibile che il consenso sia stato ottenuto nella sessione precedente. Come best practice sulla latenza, ti consigliamo di non attendere il completamento del callback per poter iniziare a caricare gli annunci il prima possibile dopo il lancio dell'app.

Se si verifica un errore durante la procedura di raccolta del consenso, devi comunque verificare se puoi richiedere gli annunci. L'SDK UMP utilizza lo stato del consenso della sessione precedente.

Il seguente esempio completo utilizza il polling del loop di aggiornamento, ma puoi utilizzare anche i callbackOnCompletion per monitorare le operazioni asincrone. Utilizza la tecnica più adatta alla struttura del tuo codice.

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

1. Chiama il numero RequestConsentInfoUpdate().

2. Controlla l'output del log per verificare la presenza di un messaggio simile all'esempio seguente, che mostra l'ID dispositivo e come aggiungerlo come dispositivo di 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. Copia l'ID del dispositivo di test negli appunti.

4. Modifica il codice per impostare ConsentRequestParameters.debug_settings.debug_device_ids su un elenco di ID dei tuoi dispositivi di 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);
   }
   

Forzare una località

L'SDK UMP fornisce un modo per testare il comportamento della tua app come se il dispositivo si trovasse in varie regioni, ad esempio nel SEE o nel Regno Unito, utilizzando debug_settings.debug_geography. Tieni presente che le impostazioni di debug funzionano solo sui dispositivi di 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);
}

Reimpostare lo stato del consenso

Durante il test della tua app con l'SDK UMP, potrebbe essere utile reimpostare lo stato dell'SDK in modo da simulare l'esperienza della prima installazione di un utente. Per farlo, l'SDK fornisce il metodo Reset().

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