L'SDK Google User Messaging Platform (UMP) è uno strumento per la privacy e la messaggistica per per aiutarti a gestire le scelte relative alla privacy. Per ulteriori informazioni, vedi Informazioni su privacy e di messaggistica.
Prerequisiti
- Livello API Android 21 o superiore (per Android)
Crea un tipo di messaggio
Crea messaggi per gli utenti con uno Tipi di messaggi per gli utenti disponibili nel menu a discesa Privacy e nella scheda Messaggistica di AdMob . L'SDK UMP tenta di visualizzare messaggio sulla privacy creato dall' AdMob ID applicazione nel progetto.
Per ulteriori dettagli, vedi Informazioni su privacy e messaggi.
Installa l'SDK
Segui i passaggi per installare Google Mobile Ads (GMA) C++ l'SDK. UMP C++ L'SDK è incluso nell'SDK GMA C++.
Assicurati di configurare l'app AdMob della tua app. ID nel progetto prima di continuare.
Nel codice, inizializza l'SDK UMP chiamando
ConsentInfo::GetInstance()
- Su Android, devi superare i
JNIEnv
eActivity
forniti da l'NDK. Devi eseguire questa operazione solo la prima volta che chiami il numeroGetInstance()
. - In alternativa, se già utilizzi lo strumento Firebase C++
SDK nella tua app, puoi passare
in
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 arrestarlo eliminando il
Istanza ConsentInfo
:
void ShutdownUserMessagingPlatform() {
ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
delete consent_info;
}
Utilizza un Future
per monitorare le operazioni asincrone
R
firebase::Future
consente di determinare lo stato di completamento di un metodo asincrono
chiamate.
Tutte le funzioni C++ di UMP e le chiamate ai metodi che operano in modo asincrono restituiscono un
Future
e fornirà anche un "ultimo risultato" per recuperare l'errore Future
dall'operazione più recente.
Esistono due modi per ottenere un risultato da un Future
:
- Chiama il numero
OnCompletion()
, passando la tua funzione di callback, che viene chiamata quando l'operazione vengono completate. - Controlla periodicamente il valore
status()
diFuture
. Quando stato cambia dakFutureStatusPending
akFutureStatusCompleted
, l'operazione è stata completata.
Dopo aver completato l'operazione asincrona, devi controllare
error()
di Future
per ottenere l'errore dell'operazione
le API nel tuo codice. Se il codice di errore è 0
(kConsentRequestSuccess
)
o kConsentFormSuccess
),
l'operazione è stata completata correttamente; altrimenti controlla il codice di errore e
error_message()
per determinare che 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 al momento dell'avvio dell'app, i risultati vengono controllati altrove, nella funzione di loop di aggiornamento del gioco (che esegue 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 l'SDK Firebase C++
documentazione
e la documentazione relativa all'SDK GMA C++.
Aggiungi l'ID applicazione
Puoi trovare il tuo ID applicazione nel UI di AdMob. Aggiungi l'ID al tuo con il seguente snippet di codice:
Richiesta di informazioni sul consenso
Devi richiedere un aggiornamento delle informazioni sul consenso dell'utente in ogni app
avvia utilizzando RequestConsentInfoUpdate()
. Questa richiesta controlla
le seguenti:
- Se il consenso è obbligatorio. Ad esempio, il consenso è richiesto per la prima volta oppure la decisione di consenso precedente è scaduta.
- Indica se è necessario un punto di ingresso per le opzioni di privacy. Alcuni messaggi sulla privacy richiedono alle app di consentire agli utenti di modificare le proprie opzioni di privacy in qualsiasi momento.
#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 presenta un modulo di messaggio sulla privacy, se necessario
Dopo aver ricevuto lo stato del consenso più aggiornato, chiama
LoadAndShowConsentFormIfRequired()
per caricare i moduli richiesti
raccogliere il consenso degli utenti. Dopo il caricamento, i moduli vengono visualizzati 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 privacy message 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 azioni dopo che l'utente ha effettuato una scelta o lo ha ignorato
del modulo, inserisci questa logica nel codice che gestisce Future
restituito da LoadAndShowConsentFormIfRequired()
.
Opzioni di privacy
Alcuni moduli di messaggi sulla privacy vengono presentati da un modello di , consentendo agli utenti di gestire le proprie opzioni di privacy in qualsiasi momento. Per scoprire di più sul messaggio che gli utenti vedono nelle opzioni di privacy del punto di accesso, consulta Tipi di messaggi per gli utenti disponibili:
Per implementare un punto di ingresso delle opzioni di privacy, completa i seguenti passaggi:
- Controlla
getPrivacyOptionsRequirementStatus()
. - Se un punto di ingresso delle opzioni di privacy aggiungi un elemento UI visibile e interattivo alla tua app.
- Attiva il modulo per le opzioni sulla privacy utilizzando
showPrivacyOptionsForm()
.
Il seguente esempio di codice illustra questi passaggi:
Richiedi annunci
Prima di richiedere annunci nella tua app, verifica di aver ottenuto il consenso
dall'utente utilizzando ConsentInfo::GetInstance()‑>CanRequestAds()
. Esistono due metodi
luoghi da controllare durante la raccolta del consenso:
- Dopo aver raccolto il consenso nella sessione corrente.
- Subito dopo aver chiamato
RequestConsentInfoUpdate()
. È possibile che il consenso sia stato ottenuto nella sessione precedente. Come latenza best practice, ti consigliamo di non attendere il completamento della richiamata per poter iniziare a caricare gli annunci il prima possibile dopo l'avvio dell'app.
Se si verifica un errore durante la procedura di raccolta del consenso, devi comunque tentare di richiedere annunci. L'SDK UMP utilizza lo stato del consenso della precedente durante la sessione.
Il seguente esempio completo utilizza il polling loop di aggiornamento, ma puoi anche utilizzare
Callback OnCompletion
per monitorare le operazioni asincrone. Utilizza le funzionalità di
a seconda della 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 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 il dispositivo di test in modo programmatico. Assicurati di rimuovere 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 impostarlo
ConsentRequestParameters.debug_settings.debug_device_ids
per 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); }
Forzare un'area geografica
L'SDK UMP consente di testare il comportamento della tua app come se il dispositivo fosse
che si trovano nel SEE 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 il
lo stato desiderato dell'SDK per simulare l'esperienza di prima installazione di un utente.
L'SDK fornisce il Reset()
metodo per farlo.
ConsentInfo::GetInstance()->Reset();