Configura l'SDK UMP

Seleziona la piattaforma: Android iOS Unity Flutter React Native Android (legacy)

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.

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 sulla privacy creato dall'ID applicazione AdMob impostato nel progetto.

Ottenere le informazioni sul consenso dell'utente

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.
• Se è necessario un punto di accesso alle opzioni sulla privacy. Alcuni messaggi sulla privacy richiedono che le app consentano agli utenti di modificare le proprie opzioni per la privacy in qualsiasi momento.

/**
 * Requests consent information update on app launch.
 */
export function requestConsent(onComplete?: () => void) {
  requestConsentInfoUpdate({}, (error) => {
    if (error) {
      console.warn('Consent info update error:', error.message);
    } else {
      console.log('Consent info update complete.');
    }

    // Load and show consent form if required.
    loadAndPresentConsentForm(onComplete);
  });
}

Avviso: non è consigliabile controllare lo stato del consenso in un altro modo, ad esempio la cache nell'app o una stringa di consenso salvata in precedenza. Questi metodi potrebbero restituire dati sul consenso dell'utente obsoleti.

Carica e presenta il modulo del messaggio sulla privacy

Dopo aver ricevuto lo stato del consenso più aggiornato, chiama loadAndShowConsentFormIfRequired() per caricare i moduli necessari per raccogliere il consenso degli utenti. Dopo il caricamento, i moduli vengono visualizzati immediatamente.

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

/**
 * Loads and presents the privacy message form if required to collect user consent.
 */
export function loadAndPresentConsentForm(onComplete?: () => void) {
  loadAndShowConsentFormIfRequired((formError) => {
    if (formError) {
      console.warn('Consent form error:', formError.message);
    } else {
      console.log('Consent gathering complete.');
    }

    // Execute logic that depends on consent state (for example, initialize the SDK).
    onComplete?.();
  });
}

Opzioni per la privacy

Alcuni moduli dei messaggi sulla privacy vengono presentati da un punto di accesso alle opzioni di privacy visualizzato dal publisher, consentendo agli utenti di gestire le proprie opzioni di privacy in qualsiasi momento. Per scoprire di più su quale messaggio viene mostrato agli utenti nel punto di accesso alle opzioni per la privacy, consulta Tipi di messaggi per gli utenti disponibili.

Verifica se è necessario un punto di accesso alle opzioni sulla privacy

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

/**
 * Helper to determine if the privacy options entry point is required.
 */
export function isPrivacyOptionsRequired(): boolean {
  return (
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED
  );
}

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

Presentare il modulo delle opzioni sulla privacy

Quando l'utente interagisce con l'elemento, presenta il modulo delle opzioni per la privacy:

/**
 * Renders a privacy options button if required by user consent policy.
 */
export function PrivacyOptionsButton({
  onDismissed,
}: {
  onDismissed?: (error?: FormError) => void;
}) {
  const isRequired =
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED;

  if (!isRequired) {
    return null;
  }

  const handleShowPrivacyOptions = () => {
    showPrivacyOptionsForm((error) => {
      if (error) {
        console.error('Failed to show privacy options form:', error.message);
      } else {
        console.log('Privacy options form dismissed.');
      }

      // Execute custom logic after form is dismissed.
      onDismissed?.(error);
    });
  };

  return <Button title="Privacy Settings" onPress={handleShowPrivacyOptions} />;
}

Richiedi annunci con il consenso dell'utente

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

/**
 * Checks whether user consent allows requesting ads and initializes the SDK.
 */
let isMobileAdsInitialized = false;

export function initializeMobileAdsSdkIfConsentGiven() {
  if (canRequestAds()) {
    if (!isMobileAdsInitialized) {
      isMobileAdsInitialized = true;
      initialize({}, (status) => {
        console.log('Google Mobile Ads SDK initialized:', status);
      });
    }
  }
}

Di seguito sono elencati i punti da controllare per 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 precedente dell'app.

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

Se si verifica un errore durante il processo di raccolta del consenso, controlla se puoi richiedere annunci. L'SDK UMP utilizza lo stato del consenso della sessione precedente dell'app.

Evita operazioni ridondanti per le richieste di annunci

Quando controlli canRequestAds() dopo aver raccolto il consenso e dopo aver chiamato requestConsentInfoUpdate(), assicurati che la logica impedisca richieste di annunci ridondanti che potrebbero comportare la restituzione di true da parte di 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 in modo programmatico il tuo dispositivo di test. Assicurati di rimuovere il codice che imposta questi ID dispositivo di test prima di rilasciare l'app.

1. Chiama il numero requestConsentInfoUpdate().

2. Controlla l'output del log per un messaggio simile al seguente esempio, 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]
   

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

4. Modifica il codice per chiamare consentDebugSettings.testDeviceIdentifiers e trasmetti un elenco degli ID dei tuoi dispositivi di test.

   /**
    * Registers a test device for testing consent flows.
    */
   export function configureTestDevice() {
     requestConsentInfoUpdate(
       {
         consentDebugSettings: {
           debugGeography: DebugGeography.DISABLED,
           testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
         },
       },
       (error) => {
         if (!error) {
           console.log('Test device registered.');
         }
       },
     );
   }

Forza un'area geografica

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

/**
 * Configures debug settings to force EEA geography on a test device.
 */
export function configureDebugGeography() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.EEA,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Consent debug test configuration loaded.');
      }
    },
  );
}

Reimposta lo stato del consenso

Durante i test della tua app con l'SDK UMP, potrebbe essere utile reimpostare lo stato dell'SDK in modo da poter simulare l'esperienza di prima installazione di un utente. L'SDK fornisce il metodo reset() per farlo.

/**
 * Resets consent state for testing purposes.
 */
export function resetConsentState() {
  reset();
}

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