Per iniziare

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, laddove richiesto dalla legge, e per l'utilizzo dei 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 UMP (User Messaging Platform). L'SDK UMP è stato aggiornato per supportare i più recenti standard IAB. Tutte queste configurazioni ora possono essere comodamente gestite in AdMob privacy e messaggi.

Prerequisiti

• Completa la Guida introduttiva

• Livello API Android 21 o successivo (per Android)

• Se lavori ai 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 i messaggi per gli utenti con uno dei tipi di messaggi per gli utenti disponibili nella scheda Privacy e messaggi del tuo AdMob account. L'SDK UMP tenta di visualizzare un messaggio utente creato dall' AdMob ID applicazione impostato nel progetto. Se non è configurato alcun messaggio per la tua applicazione, l'SDK restituisce un errore.

Per maggiori dettagli, consulta Informazioni su privacy e messaggi.

Installa l'SDK

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

2. Assicurati di configurare l'ID app AdMob dell'app nel progetto prima di continuare.

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

   • Su Android, devi trasmettere JNIEnv e Activity forniti da NDK. Devi eseguire questa operazione solo la prima volta che chiami GetInstance().
   • In alternativa, se già utilizzi l'SDK Firebase C++ nella tua app, puoi trasmettere 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.

Nota: i metodi GetInstance() hanno un parametro di output facoltativo firebase::InitResult che restituisce firebase::kInitResultSuccess se l'SDK è stato inizializzato correttamente, oppure firebase::kInitResultFailedMissingDependency se l'applicazione è priva di eventuali dipendenze obbligatorie. Se si verifica questo errore, assicurati di aver seguito tutti i passaggi di installazione relativi alla tua piattaforma.

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

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

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

Utilizza un elemento Future per monitorare le operazioni asincrone

Un firebase::Future offre un modo per determinare lo stato di completamento delle chiamate ai metodi asincroni.

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

Esistono due modi per ottenere un risultato da un elemento Future:

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

Al termine dell'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.

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

Callback di completamento

Ecco un esempio di come utilizzare OnCompletion per impostare un callback di completamento, che viene chiamato quando viene completata l'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 del 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 sull'SDK Firebase C++ e la documentazione sull'SDK GMA C++.

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

Richiesta di informazioni sul consenso

Devi richiedere un aggiornamento delle informazioni sul consenso dell'utente a ogni lancio dell'app, utilizzando RequestConsentInfoUpdate(). Questo determina se l'utente deve dare il consenso nel caso in cui non l'abbia già fatto o se il consenso è 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 un esempio di controllo del completamento utilizzando il polling del loop di aggiornamento anziché un callback di completamento.

Avviso: l'utilizzo di altri metodi per controllare lo stato del consenso, come la cache nell'app o una stringa per il consenso salvata in precedenza, potrebbe generare un errore TCF 3.3 quando il consenso è scaduto.

Carica e mostra un modulo di consenso, se necessario

Dopo aver ricevuto lo stato del consenso più aggiornato, chiama LoadAndShowConsentFormIfRequired() il ConsentInfo corso per caricare un modulo di consenso. Se lo stato del consenso è obbligatorio, l'SDK carica un modulo e lo presenta immediatamente dal FormParentspecificato. Il Future completamento dopo che il modulo viene ignorato. Se il consenso non è richiesto, il Future completato immediatamente.

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

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 azioni dopo che l'utente ha effettuato una scelta o ignorato il modulo, inserisci tale logica nel codice che gestisce l'elemento Future restituito da LoadAndShowConsentFormIfRequired().

Richiedi annunci

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

1. Una volta ottenuto il consenso nella sessione corrente.
2. Subito dopo aver chiamato RequestConsentInfoUpdate(). È possibile che il consenso sia stato ottenuto nella sessione precedente. Come best practice in materia di latenza, ti consigliamo di non attendere il completamento del callback in modo da poter iniziare a caricare gli annunci il prima possibile dopo l'avvio dell'app.

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

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

Il seguente esempio completo utilizza il polling in loop di aggiornamento, ma puoi anche utilizzare i callback OnCompletion per monitorare le operazioni asincrone. Utilizza la tecnica che meglio si 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 relative alla privacy

Alcuni moduli di consenso richiedono all'utente di modificare il consenso in qualsiasi momento. Rispetta i seguenti passaggi per implementare un pulsante Opzioni di privacy, se necessario.

A questo scopo:

1. Implementa un elemento UI, ad esempio un pulsante nella pagina delle impostazioni dell'app, che può attivare un modulo delle opzioni di privacy.
2. Una volta LoadAndShowConsentFormIfRequired() completato, controlla getPrivacyOptionsRequirementStatus() per determinare se visualizzare l'elemento UI che può presentare il modulo delle opzioni di privacy.
3. Quando un utente interagisce con il tuo elemento UI, chiamashowPrivacyOptionsForm() per mostrare il modulo in modo che l'utente possa aggiornare le opzioni sulla privacy in qualsiasi momento.

Test

Se vuoi testare l'integrazione nella tua app durante lo sviluppo, segui i passaggi riportati di seguito per registrare in modo programmatico il dispositivo di test.

1. Chiama il numero RequestConsentInfoUpdate().

2. Controlla se nell'output del log è presente un messaggio simile a quello riportato di seguito, che mostra l'ID del tuo 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 impostarlo 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);
}

Nota: assicurati di rimuovere il codice che imposta questi ID dispositivo di test prima di rilasciare l'app.

Forzare un'area geografica

L'SDK UMP ti consente di testare il comportamento della tua app come se il dispositivo si trovasse 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 lo stato dell'SDK in modo da simulare la prima installazione di un utente. L'SDK fornisce il Reset() metodo 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.