Secondo le Norme relative al consenso degli utenti dell'UE di Google, è obbligatorio informare gli utenti nello Spazio economico europeo (SEE) e nel Regno Unito e ricevere il loro consenso per l'utilizzo dei cookie o di altri tipi di archiviazione locale, ove richiesto dalla legge, nonché di utilizzare dati personali (ad esempio l'ID pubblicità) per la pubblicazione di annunci. Queste norme riflettono i requisiti della direttiva e-Privacy e del Regolamento generale sulla protezione dei dati (GDPR) dell'UE.
Per supportare i publisher nell'adempimento degli obblighi previsti da queste norme, Google offre l'SDK User Messaging Platform (UMP). L'SDK UMP è stato aggiornato per supportare i più recenti standard IAB. Ora tutte queste configurazioni possono essere gestite comodamente nella sezione AdMob Privacy e messaggi.
Prerequisiti
- Completa la Guida introduttiva
- Livello API Android 21 o superiore (per Android)
- Se ti occupi dei requisiti relativi al GDPR, leggi In che modo i requisiti IAB influiscono sui messaggi per il consenso dell'UE
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 utente creato dall' AdMob ID applicazione impostato nel progetto. Se non viene configurato alcun messaggio per la tua applicazione, l'SDK restituisce un errore.
Per maggiori dettagli, consulta Informazioni su privacy e messaggi.
Installa l'SDK
Segui i passaggi per installare l'SDK Google Mobile Ads (GMA) C++. L'SDK UMP C++ è incluso nell'SDK GMA C++.
Assicurati di configurare l'ID app AdMob dell'app nel progetto prima di continuare.
Nel codice, inizializza l'SDK UMP chiamando
ConsentInfo::GetInstance()
.- Su Android, devi superare i
JNIEnv
e iActivity
forniti dall'NDK. Devi eseguire questa operazione solo la prima volta che chiami il numeroGetInstance()
. - In alternativa, se utilizzi già l'SDK Firebase C++ nella tua app, puoi passare
un
firebase::App
la prima volta che chiamiGetInstance()
.
#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
- Su Android, devi superare i
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
offre un modo per determinare lo stato di completamento delle chiamate di metodi asincroni.
Tutte le funzioni e le chiamate al metodo C++ di UMP che operano in modo asincrono restituiscono un
Future
e forniscono inoltre una funzione "ultimo risultato" per recuperare Future
dall'operazione più recente.
Esistono due modi per ottenere un risultato da un Future
:
- Richiama
OnCompletion()
, passando la tua funzione di callback, che viene chiamata al completamento dell'operazione. - Controlla periodicamente il valore
status()
diFuture
. Quando lo stato cambia dakFutureStatusPending
akFutureStatusCompleted
, l'operazione è stata completata.
Dopo aver completato l'operazione asincrona, devi controllare il valore 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 non ha funzionato.
Callback di completamento
Ecco un esempio di come utilizzare OnCompletion
per impostare un callback di completamento, che viene chiamato al completamento 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.
}
});
}
Aggiorna polling loop
In questo esempio, dopo l'avvio di un'operazione asincrona all'avvio dell'app, i risultati vengono controllati altrove, nella funzione di loop 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 ulteriori informazioni su firebase::Future
, consulta la documentazione relativa all'SDK Firebase C++ e la documentazione relativa all'SDK GMA C++.
Richiesta di informazioni sul consenso
Devi richiedere un aggiornamento delle informazioni sul consenso dell'utente a ogni avvio dell'app utilizzando RequestConsentInfoUpdate()
. In questo modo viene stabilito se l'utente deve fornire il consenso, se non l'ha già fatto o se è scaduto.
#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.
}
});
}
Vedi sopra per un esempio di controllo del completamento utilizzando il polling del loop di aggiornamento anziché un callback di completamento.
Carica e mostra un modulo di consenso, se necessario
Dopo aver ricevuto lo stato del consenso più aggiornato, chiama
LoadAndShowConsentFormIfRequired()
il corso
ConsentInfo
per caricare un modulo di consenso. Se lo
stato del consenso è obbligatorio, l'SDK carica un modulo e lo presenta immediatamente
dal FormParent
fornito. Il campo Future
viene completato dopo che il modulo è stato ignorato. Se il consenso non è richiesto, il Future
recupero viene completato immediatamente.
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 consent form: %s", form_result.error_message());
} else {
// Either the form was shown and completed by the user, or consent was not required.
}
});
}
});
}
Se devi eseguire delle azioni dopo che l'utente ha scelto o ignorato il modulo, inserisci questa logica nel codice che gestisce il Future
restituito da LoadAndShowConsentFormIfRequired()
.
Richiedi annunci
Prima di richiedere annunci nella tua app, verifica di aver ottenuto il consenso
da parte dell'utente che utilizza ConsentInfo::GetInstance()‑>CanRequestAds()
. Ci sono due
punti da controllare durante la raccolta del consenso:
- Una volta raccolto il consenso 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, dovresti comunque tentare di 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 anche utilizzare i
callback OnCompletion
per monitorare le operazioni asincrone. Utilizza la tecnica più adatta alla struttura del 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 consent 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;
}
}
}
}
Opzioni di privacy
Alcuni moduli di consenso richiedono all'utente di modificare il proprio consenso in qualsiasi momento. Segui i passaggi riportati di seguito per implementare un pulsante delle opzioni sulla privacy, se necessario.
A questo scopo:
- Implementare un elemento UI, ad esempio un pulsante nella pagina delle impostazioni dell'app, che può attivare un modulo per le opzioni sulla privacy.
- Una volta
LoadAndShowConsentFormIfRequired()
completato, controllagetPrivacyOptionsRequirementStatus()
per stabilire se visualizzare l'elemento UI che può presentare il modulo delle opzioni di privacy. - Quando un utente interagisce con l'elemento UI, chiama
showPrivacyOptionsForm()
per mostrare il modulo in modo che l'utente possa aggiornare le proprie opzioni di privacy in qualsiasi momento.
Test in corso
Se vuoi testare l'integrazione nella tua app durante lo sviluppo, segui questi passaggi per registrare il dispositivo di test in modo programmatico. Assicurati di rimuovere il codice che imposta questi ID dispositivo di test prima di rilasciare l'app.
- Chiama il numero
RequestConsentInfoUpdate()
. Controlla nell'output del log 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 del dispositivo di test negli appunti.
Modifica il codice per impostare
ConsentRequestParameters.debug_settings.debug_device_ids
su un elenco dei tuoi 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); }
Forzare un'area geografica
L'SDK UMP consente di testare il comportamento della tua app come se il dispositivo si trovasse nello Spazio economico europeo o nel Regno Unito utilizzando ConsentRequestParameters.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 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.
L'SDK fornisce il Reset()
metodo per farlo.
ConsentInfo::GetInstance()->Reset();