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 la pagina 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 dall'ID applicazione AdMob impostato nel tuo progetto.

Per maggiori dettagli, consulta la pagina Informazioni su privacy e messaggi.

Installa l'SDK

Segui i passaggi per installare l'SDK Firebase C++. L'SDK UMP C++ è incluso nell'SDK Firebase C++.
Prima di continuare, assicurati di configurare l'ID app AdMob della tua app nel progetto prima di continuare.

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

Su Android, devi passare JNIEnv e Activity forniti dall'NDK. Devi 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.

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

A 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:

Chiama OnCompletion(), passando la tua funzione di callback, che viene chiamata al termine dell'operazione
Controlla periodicamente status() di Future. Quando lo stato passa da kFutureStatusPending a kFutureStatusCompleted, l' operazione è stata completata.

Al termine dell'operazione asincrona, devi controllare error() di Future 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.

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

Polling del ciclo di aggiornamento

In questo esempio, dopo l'avvio di un'operazione asincrona all'avvio dell'app, i risultati vengono controllati altrove, nella funzione del 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++.

Ottieni 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 è richiesto il consenso. Ad esempio, il consenso è richiesto per la prima volta o la decisione sul consenso precedente è scaduta.
Se è richiesto un punto di contatto per le opzioni sulla privacy. Alcuni messaggi sulla privacy richiedono che le app consentano agli utenti di modificare le proprie opzioni sulla 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.
    });
}

Carica e presenta il modulo del messaggio sulla privacy

Dopo aver ricevuto lo stato del consenso più aggiornato, chiama LoadAndShowConsentFormIfRequired() per caricare tutti i moduli necessari per raccogliere il consenso dell'utente. Dopo il caricamento, i moduli vengono presentati 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.
          }
        });
      }
    });
}

Vedi sopra un esempio di controllo del completamento utilizzando il polling del ciclo di aggiornamento anziché un callback di completamento.

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

Opzioni sulla privacy

Alcuni moduli di messaggi sulla privacy vengono presentati da un punto di accesso alle opzioni sulla privacy sottoposto a rendering dal publisher, consentendo agli utenti di gestire le proprie opzioni sulla privacy in qualsiasi momento. Per scoprire di più su quale messaggio viene mostrato agli utenti nel punto di accesso alle opzioni sulla privacy, consulta la pagina Tipi di messaggi per gli utenti disponibili.

Richiedi annunci con il consenso dell'utente

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

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

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

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

Evita il lavoro di richiesta di annunci ridondante

Quando controlli ConsentInfo::GetInstance()‑> CanRequestAds() dopo aver raccolto il consenso e dopo aver chiamato RequestConsentInfoUpdate(), assicurati che la tua logica impedisca richieste di annunci ridondanti che potrebbero comportare la restituzione di true da entrambi i controlli. Ad esempio, con una variabile booleana.

L'esempio completo seguente utilizza il polling del ciclo di aggiornamento, ma puoi anche utilizzare OnCompletion callback 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 in modo programmatico il tuo dispositivo di test. Assicurati di rimuovere il codice che imposta questi ID dispositivo di test prima di rilasciare l'app.

Chiama RequestConsentInfoUpdate().

Controlla l'output del log per 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]

Copia l'ID dispositivo di test negli appunti.

Modifica il codice per impostare ConsentRequestParameters.debug_settings.debug_device_ids su un elenco degli ID dispositivo 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);
}

Forza una località geografica

L'SDK UMP offre un modo per testare il comportamento della tua app come se il dispositivo si trovasse in varie regioni, come lo Spazio Economico Europeo (SEE), il Regno Unito e la Svizzera, 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 in modo da simulare l'esperienza di prima installazione di un utente. L'SDK fornisce il metodo Reset() per farlo.

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