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 ulteriori informazioni, consulta Informazioni su Privacy e messaggi.

Prerequisiti

• Livello API Android 21 o superiore

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 account AdMob. L'SDK UMP tenta di visualizzare un messaggio sulla privacy creato dall'ID applicazione AdMob impostato nel progetto.

Per maggiori dettagli, consulta Informazioni su privacy e messaggi.

Installazione con Gradle

Aggiungi la dipendenza per l'SDK Google User Messaging Platform al file Gradle a livello di app del modulo, in genere app/build.gradle:

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}

Dopo aver apportato le modifiche all'elemento build.gradle dell'app, assicurati di sincronizzare il progetto con i file Gradle.

Aggiungi l'ID applicazione

Puoi trovare l'ID applicazione nell'interfaccia utente di AdMob. Aggiungi l'ID a AndroidManifest.xml con lo snippet di codice seguente:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

Raccogli il consenso

Per raccogliere il consenso:

1. Richiedi le informazioni più recenti sul consenso dell'utente.
2. Carica e presenta un modulo di consenso, se necessario.

Richiesta di informazioni sul consenso

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

• Se il consenso è obbligatorio. Ad esempio, il consenso è richiesto per la prima volta o 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 loro opzioni sulla privacy in qualsiasi momento.

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 per raccogliere il consenso degli utenti. Dopo il caricamento, i moduli vengono visualizzati immediatamente.

Il seguente codice mostra come richiedere le informazioni più recenti sul consenso dell'utente. Se necessario, il codice carica e mostra un modulo di messaggio sulla privacy:

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity,
            formError -> {
              // Consent has been gathered.
              onConsentGatheringCompleteListener.consentGatheringComplete(formError);
            }),
    requestConsentError ->
        onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError));
GoogleMobileAdsConsentManager.java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
      // Consent has been gathered.
      onConsentGatheringCompleteListener.consentGatheringComplete(formError)
    }
  },
  { requestConsentError ->
    onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError)
  },
)
GoogleMobileAdsConsentManager.kt

Opzioni per la privacy

Alcuni moduli di messaggi sulla privacy vengono presentati da un punto di contatto per le opzioni di privacy visualizzato dal publisher, che consente agli utenti di gestire le proprie opzioni di privacy in qualsiasi momento. Per scoprire di più sul messaggio visualizzato dagli utenti nel punto di immissione delle opzioni sulla privacy, consulta Tipi di messaggi per gli utenti disponibili.

Verificare se è richiesto un punto di ingresso per le opzioni di privacy

Dopo aver chiamato requestConsentInfoUpdate(), controlla getPrivacyOptionsRequirementStatus() per determinare se è necessario un punto di accesso per le opzioni di privacy per la tua app:

/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
GoogleMobileAdsConsentManager.java

/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
GoogleMobileAdsConsentManager.kt

Aggiungere un elemento visibile all'app

Se è necessario un punto di accesso alla privacy, aggiungi alla tua app un elemento UI visibile e interattivo che presenti il modulo delle opzioni sulla privacy. Se non è richiesto un punto di ingresso per la privacy, configura l'elemento UI in modo che non sia visibile e non possa essere interagito.

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}
MyActivity.java

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}
MainActivity.kt

Presentare il modulo relativo alle opzioni per la privacy

Quando l'utente interagisce con il tuo elemento, presenta il modulo delle opzioni della privacy:

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
GoogleMobileAdsConsentManager.java

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Richiedi annunci

Prima di richiedere gli annunci nella tua app, controlla se hai ottenuto il consenso dell'utente utilizzando canRequestAds(). Esistono due punti da controllare durante la raccolta del consenso:

• Dopo che il consenso è stato raccolto nella sessione corrente.
• Subito dopo aver chiamato requestConsentInfoUpdate(). È possibile che il consenso sia stato ottenuto nella sessione precedente. Come best practice per la 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, devi comunque verificare se puoi richiedere gli annunci. L'SDK UMP utilizza lo stato del consenso della sessione precedente.

Il seguente codice verifica se puoi richiedere annunci durante la procedura di raccolta del consenso:

googleMobileAdsConsentManager.gatherConsent(
    this,
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.w(
            TAG,
            String.format("%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (googleMobileAdsConsentManager.canRequestAds()) {
        initializeMobileAdsSdk();
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds()) {
  initializeMobileAdsSdk();
}

googleMobileAdsConsentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(TAG, "${error.errorCode}: ${error.message}")
  }

  if (googleMobileAdsConsentManager.canRequestAds) {
    initializeMobileAdsSdk()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds) {
  initializeMobileAdsSdk()
}

Il seguente codice configura l'SDK Google Mobile Ads dopo la raccolta del consenso dell'utente:

private void initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return;
  }
  new Thread(
          () -> {
            // Initialize the Google Mobile Ads SDK on a background thread.
            MobileAds.initialize(this, initializationStatus -> {});

            // Load an ad on the main thread.
            runOnUiThread(this::loadBanner);
          })
      .start();
}
MyActivity.java

private fun initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return
  }
  CoroutineScope(Dispatchers.IO).launch {
    // Initialize the Google Mobile Ads SDK on a background thread.
    MobileAds.initialize(this@MainActivity) {}

    runOnUiThread {
      // Load an ad on the main thread.
      loadBanner()
    }
  }
}
MainActivity.kt

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 il codice che imposta questi ID dispositivo di test prima di rilasciare l'app.

1. Chiama il numero requestConsentInfoUpdate().

2. Controlla nell'output del log un messaggio simile all'esempio seguente, che mostra l'ID dispositivo e come aggiungerlo come dispositivo di test:

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
   

3. Copia l'ID del dispositivo di test negli appunti.

4. Modifica il codice per chiamare ConsentDebugSettings.Builder().TestDeviceHashedIds e passare in un elenco di ID dispositivo di test.

   Java

   ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build();
   
   ConsentRequestParameters params = new ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build();
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this);
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   );
   

   Kotlin

   val debugSettings = ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build()
   
   val params = ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build()
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this)
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   )
   

Forzare una località

L'SDK UMP consente di testare il comportamento della tua app come se il dispositivo si trovasse in varie regioni, ad esempio SEE o Regno Unito, utilizzando setDebugGeography(). Tieni presente che le impostazioni di debug funzionano solo sui dispositivi di test.

ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
);

val debugSettings = ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
)

Reimpostare lo 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. Per farlo, l'SDK fornisce il metodo reset().

consentInformation.reset();

consentInformation.reset()

Esempi su GitHub

Puoi trovare un esempio completo dell'integrazione dell'SDK UMP descritta in questa pagina in Java BannerExample e Kotlin BannerExample.