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 versioni successive (per Android)

Crea un tipo di messaggio

Crea 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 a partire dall'ID applicazione AdMob impostato nel progetto.

Per maggiori dettagli, consulta Informazioni su privacy e messaggi.

Installa l'SDK

1. Segui i passaggi per installare l'SDK Firebase C++. L'SDK UMP C++ è incluso nell'SDK Firebase 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 trasmettere JNIEnv e Activity forniti dall'NDK. Dovrai farlo 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/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
   

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

Nota :i metodi GetInstance() hanno un parametro di output facoltativo firebase::InitResult che restituisce firebase::kInitResultSuccess se l'SDK è stato inizializzato correttamente o firebase::kInitResultFailedMissingDependency se mancano dipendenze richieste nell'applicazione. Se si verifica questo errore, assicurati di aver seguito tutti i passaggi di installazione per la tua piattaforma.

Se hai terminato di utilizzare l'SDK UMP, puoi chiuderla eliminando l'istanza ConsentInfo:

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

Nota: non è necessario inizializzare l'SDK Firebase C++ prima di inizializzare l'SDK User Messaging Platform.

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 metodi 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. Chiama OnCompletion(), passando la tua funzione di callback, che viene chiamata al termine dell'operazione.
2. Controlla periodicamente i Futuredell'status(). Quando lo stato passa da kFutureStatusPending a kFutureStatusCompleted, l'operazione è stata completata.

Al termine dell'operazione asincrona, devi controllare Future di error() per ottenere il codice di 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 è andato storto.

Nota: il codice di errore restituito da RequestConsentInfoUpdate() utilizza l'enum ConsentRequestError; tutte le altre operazioni utilizzano ConsentFormError.

Callback di completamento

Ecco un esempio di come utilizzare OnCompletion per impostare un callback di completamento, che viene chiamato al termine dell'operazione asincrona.

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

Aggiornamento del polling del ciclo

In questo esempio, dopo l'avvio di un'operazione asincrona all'avvio dell'app, i risultati vengono controllati altrove, nella funzione di ciclo di aggiornamento del gioco (che viene eseguita una volta per 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.
      }
    }
  }
}

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

Nota :nell'SDK UMP C++, tutte le operazioni asincrone restituiscono firebase::Future<void>.

Ottenere le informazioni sul consenso dell'utente

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

• Se è necessario il consenso. Ad esempio, il consenso è richiesto per la prima volta o la decisione precedente relativa al consenso è scaduta.
• Se è richiesto un punto di accesso alle opzioni sulla privacy. Alcuni messaggi relativi alla privacy richiedono alle app di consentire agli utenti di modificare le proprie opzioni per la privacy in qualsiasi momento.

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

Avviso: l'utilizzo di altri modi per verificare lo stato del consenso, ad esempio la cache dell'app o una stringa di consenso salvata in precedenza, può comportare un errore TCF 3.3 se il consenso è scaduto.

Carica e presenta il modulo del messaggio sulla privacy

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

Punto chiave: se nessun modulo di messaggio relativo alla privacy richiede la raccolta del consenso dell'utente prima di richiedere gli annunci, il callback viene richiamato immediatamente.

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

Consulta l'esempio sopra per verificare il completamento utilizzando il polling del ciclo di aggiornamento anziché un callback di completamento.

Nota: a seconda della piattaforma, FormParent è un riferimento JNI a un Activity Android o un puntatore a un UIViewController iOS, convertito in un tipo FormParent.

jobject

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

Opzioni per la privacy

Alcuni moduli di messaggi relativi alla privacy vengono presentati da una sezione in cui specificare le opzioni di privacy visualizzata dall'editore, consentendo agli utenti di gestire le proprie opzioni di privacy in qualsiasi momento. Per scoprire di più su quale messaggio viene visualizzato dagli utenti nel punto di accesso alle opzioni della privacy, consulta Tipi di messaggi per gli utenti disponibili.

Richiedere annunci con il consenso dell'utente

Prima di richiedere annunci, utilizza ConsentInfo::GetInstance()‑> CanRequestAds() per verificare se hai ottenuto il consenso dell'utente:

Di seguito sono elencati i luoghi in cui puoi verificare se puoi richiedere annunci durante la raccolta del consenso:

• Dopo che l'SDK UMP raccoglie il consenso nella sessione corrente.
• Subito dopo aver chiamato il numero RequestConsentInfoUpdate(). L'SDK UMP potrebbe aver ottenuto il consenso nella sessione precedente dell'app.

Importante: ConsentInfo::GetInstance()‑> CanRequestAds() restituisce sempre false finché non hai chiamato RequestConsentInfoUpdate()

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

Il seguente esempio completo utilizza il polling del ciclo di aggiornamento, ma puoi anche utilizzare i callback OnCompletion 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/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;
      }
    }
  }
}

Test

Se vuoi testare l'integrazione nella tua app durante lo sviluppo, segui questi passaggi per registrare a livello di programmazione il tuo dispositivo di test. Assicurati di rimuovere il codice che imposta questi ID dispositivo di test prima di rilasciare l'app.

1. Chiama il numero RequestConsentInfoUpdate().

2. Controlla l'output del log per un messaggio simile al seguente esempio, 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 dispositivo di test negli appunti.

4. Modifica il codice per impostare ConsentRequestParameters.debug_settings.debug_device_ids su un elenco degli 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 un'area geografica

L'SDK UMP offre un modo per testare il comportamento della tua app come se il dispositivo si trovasse in varie regioni, ad esempio il SEE o il 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);
}

Reimposta lo stato del consenso

Quando testi la tua app con l'SDK UMP, potrebbe essere utile reimpostare lo stato dell'SDK per simulare l'esperienza di prima installazione di un utente. L'SDK fornisce il metodo Reset() per farlo.

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

Attenzione: questo metodo è destinato a essere utilizzato solo a scopo di test. Non devi chiamare Reset() nel codice di produzione.