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 Informazioni su Privacy e messaggi. Puoi vedere un'implementazione IMA funzionante con l'SDK UMP nell'app di esempio UMP.

Prerequisiti

• Livello API Android 21 o superiore

Creare 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 Ad Manager. L'SDK UMP tenta di mostrare un messaggio sulla privacy creato dall'ID applicazione Interactive Media Ads impostato nel progetto.

Per ulteriori 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 al build.gradle dell'app, assicurati di sincronizzare il progetto con i file Gradle.

Aggiungi l'ID applicazione

Puoi trovare il tuo ID applicazione nell'interfaccia utente di Ad Manager. 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>

Ottenere le informazioni sul consenso dell'utente

Per ottenere le informazioni sul consenso dell'utente, svolgi i seguenti passaggi:

Dichiara un'istanza di ConsentInformation:

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

Inizializza l'istanza ConsentInformation:

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

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

• Se il consenso è obbligatorio. Ad esempio, il consenso è richiesto per la prima volta o la decisione di consenso precedente è scaduta.
• Se è richiesto un punto di accesso alle opzioni sulla privacy. Alcuni messaggi sulla privacy richiedono alle app di consentire agli utenti di modificare le proprie opzioni sulla privacy in qualsiasi momento.

Java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () -> // Called when consent information is successfully updated.
    requestConsentError -> // Called when there's an error updating consent information.
ConsentManager.java

Kotlin

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    // Called when consent information is successfully updated.
  },
  { requestConsentError -> // Called when there's an error updating consent information.


},
)

Avviso: l'utilizzo di altri modi per controllare lo stato del consenso, ad esempio la cache della tua app o una stringa di consenso salvata in precedenza, può comportare un errore TCF 3.3 se il consenso è scaduto.

Carica e presenta il modulo del messaggio sulla privacy

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.

Punto chiave: se nessun modulo del messaggio sulla privacy richiede la raccolta del consenso dell'utente prima di richiedere gli annunci, il callback viene richiamato immediatamente.

Java

UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });
ConsentManager.java

Kotlin

UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering is complete.
}

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 accesso alle opzioni della privacy, consulta Tipi di messaggi per gli utenti disponibili.

Verificare se è richiesto un punto di accesso alle opzioni sulla privacy

Dopo aver chiamato requestConsentInfoUpdate(), controlla getPrivacyOptionsRequirementStatus() per determinare se è necessario un punto di accesso alle opzioni sulla privacy per la tua app. Se è necessario un punto di accesso, aggiungi alla tua app un elemento dell'interfaccia utente visibile e interattivo che presenti il modulo delle opzioni sulla privacy. Se non è richiesto un punto di contatto per la privacy, configura l'elemento dell'interfaccia utente in modo che non sia visibile e interattivo.

Java

/** Helper function to determine if a privacy options entry point is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
ConsentManager.java

Kotlin

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

Per l'elenco completo degli stati dei requisiti delle opzioni sulla privacy, consulta ConsentInformation.PrivacyOptionsRequirementStatus.

Presentare il modulo relativo alle opzioni per la privacy

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

Java

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

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

Richiedere annunci con il consenso dell'utente

Prima di richiedere gli annunci, utilizza canRequestAds() per verificare se hai ottenuto il consenso dell'utente:

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

Di seguito sono elencati i luoghi in cui puoi verificare se puoi richiedere 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.

Importante: canRequestAds() restituisce sempre false finché non hai chiamato requestConsentInfoUpdate()

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.

Evitare attività di richiesta di annunci ridondanti

Quando controlli canRequestAds() dopo aver raccolto il consenso e dopo aver chiamato requestConsentInfoUpdate(), assicurati che la tua logica impedisca richieste di annunci ridondanti che potrebbero comportare il ritorno di true in entrambi i controlli. Ad esempio, con una variabile booleana.

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.

Nota: a partire dalla versione 2.2.0, gli emulatori non devono essere aggiunti all'elenco di ID dispositivo perché sono dispositivi di test per impostazione predefinita.

1. Chiama il numero requestConsentInfoUpdate().

2. Controlla l'output del log per verificare la presenza di 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 in modo da chiamare ConsentDebugSettings.Builder().addTestDeviceHashedId() e passare un elenco di ID dei dispositivi 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 fornisce un modo per verificare il comportamento della tua app come se il dispositivo si trovasse in varie regioni, ad esempio nel SEE o nel Regno Unito, utilizzando DebugGeography. Tieni presente che le impostazioni di debug funzionano solo sui dispositivi di test.

Java

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

Kotlin

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

Quando testi la tua app con l'SDK UMP, potresti trovare utile reimpostare lo stato dell'SDK in modo da poter simulare la prima esperienza di installazione di un utente. L'SDK fornisce il metodo reset() per farlo.

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

Attenzione: questo metodo è destinato esclusivamente a scopi di test. Non chiamare reset() nel codice di produzione.

Esempi su GitHub

Consulta un esempio completo dell'integrazione dell'SDK UMP descritto in questa pagina in UmpExample.