Richiedere indicatori dell'età

Questo documento descrive come richiedere indicatori dell'età utilizzando l'API Play Age Signals.

L'SDK Play Age Signals 0.0.4 introduce un'architettura a due funzioni progettata per semplificare le richieste di indicatori di età e supportare il nostro modello basato sulla scelta dell'utente. Per richiedere indicatori dell'età, utilizza questo flusso di lavoro di alto livello:

Chiama il metodo requestAgeSignalsAccess(Activity), che restituisce ageSignalsStatus. Il valore di ageSignalsStatus può essere SHARED, NOT_SHARED o VERIFICATION_REQUIRED.

  • Se ageSignalsStatus == NOT_SHARED: la tua app non riceverà indicatori dell'età nella risposta dell'API.
  • Se ageSignalsStatus == SHARED: chiama il metodo checkAgeSignals(). Se l'utente o il genitore ha deciso di condividere gli indicatori di età, ricevi gli indicatori di età come parte della risposta dell'API e puoi decidere come gestirla.
  • Se ageSignalsStatus == VERIFICATION_REQUIRED: l'età dell'utente è sconosciuta e l'utente si trova in una giurisdizione o regione applicabile in cui la verifica dell'età e la condivisione degli indicatori dell'età sono obbligatorie. Per ottenere un segnale di età da Google Play in queste regioni, chiedi all'utente di visitare il Play Store per risolvere il suo stato.

Il metodo requestAgeSignalsAccess(Activity) restituisce valori diversi a seconda che la condivisione obbligatoria dell'età sia applicabile in una regione:

  • Per gli utenti idonei negli stati degli Stati Uniti con leggi che richiedono agli store di fornire informazioni sull'età verificate agli sviluppatori, il prompt in-app non viene attivato. Agli utenti verrà invece chiesto di verificare l'età o configurare la supervisione quando visitano l'app Play Store. Utilizza il valore di ageSignalsStatus per determinare lo stato di verifica:
  • Per gli utenti di altre regioni in cui la condivisione dell'età si basa sulla scelta dell'utente o del genitore:
    • Se l'impostazione dell'utente è Chiedi prima di condividere, viene visualizzato il prompt in-app. Se l'utente accetta di condividere la propria età, il valore di ageSignalsStatus è SHARED; altrimenti, NOT_SHARED.
    • Se l'impostazione dell'utente è Condividi sempre, il prompt in-app non viene mostrato e il valore di ageSignalsStatus è SHARED.
    • Se l'impostazione dell'utente è Non condividere mai, il prompt in-app non viene mostrato e il valore di ageSignalsStatus è NOT_SHARED.
    • Per gli utenti supervisionati, i genitori possono scegliere di condividere l'età del proprio figlio nelle impostazioni dell'app Family Link. Se i genitori scelgono di condividere l'età, il valore di ageSignalsStatus sarà SHARED, altrimenti sarà NOT_SHARED.

L'immagine seguente mostra la configurazione della fascia d'età Chiedi prima di condividere nelle impostazioni di Play.

Menu delle impostazioni di Google Play che mostra le opzioni per la condivisione dell'età: Chiedi prima di condividere, Condividi sempre e Non condividere mai
Figura 1. Gestisci la condivisione dell'età nelle impostazioni di Play.

L'immagine seguente mostra la richiesta di condivisione della fascia d'età in-app visualizzata dagli utenti quando l'età viene richiesta tramite l'API e l'impostazione è Chiedi prima di condividere.

Finestra di dialogo per il consenso in-app che chiede all'utente di condividere la propria fascia d'età con l'app.
Figura 2. Richiesta di condivisione della fascia d'età in-app.

L'immagine seguente mostra come l'utente può attivare o disattivare la condivisione dell'età per un'app specifica.

Finestra di dialogo delle impostazioni per un'app specifica che mostra un pulsante di attivazione/disattivazione per abilitare o disabilitare la condivisione della fascia d'età
Figura 3. Attiva o disattiva la condivisione dell'età per un'app specifica.

Il seguente esempio mostra come richiedere i segnali relativi all'età:

Kotlin

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
val ageSignalsManager = AgeSignalsManagerFactory.create(applicationContext)

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
val accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build()

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener { accessResult ->
        if (accessResult.ageSignalsStatus() == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager)
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    }
    .addOnFailureListener { exception ->
        // Handle API/Play Store connection and system errors
        handleAgeSignalsError(exception)
    }

private fun retrieveAgeSignals(manager: AgeSignalsManager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener { ageSignalsResult ->
            val installId = ageSignalsResult.installId()
            val ageLower = ageSignalsResult.ageLower()
            val ageUpper = ageSignalsResult.ageUpper()
            val significantChangeDate = ageSignalsResult.significantChangeApprovalDate()
            val ageRangeSource = ageSignalsResult.ageRangeSource()

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
            }
        }
        .addOnFailureListener { exception ->
            handleAgeSignalsError(exception)
        }
}

Java

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
AgeSignalsManager ageSignalsManager = AgeSignalsManagerFactory.create(getApplicationContext());

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
AgeSignalsAccessRequest accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build();

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener(accessResult -> {
        Integer status = accessResult.ageSignalsStatus();
        if (status == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager);
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    })
    .addOnFailureListener(exception -> {
        // Handle API/Play Store connection and system errors
    });

private void retrieveAgeSignals(AgeSignalsManager manager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener(ageSignalsResult -> {
            String installId = ageSignalsResult.installId();
            Integer ageLower = ageSignalsResult.ageLower();
            Integer ageUpper = ageSignalsResult.ageUpper();
            Date significantChangeDate = ageSignalsResult.significantChangeApprovalDate();
            @AgeRangeSource Integer ageRangeSource = ageSignalsResult.ageRangeSource();

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
            }
        })
        .addOnFailureListener(exception -> {
            handleAgeSignalsError(exception);
        });
}

Punti chiave sul codice

  • Il metodo requestAgeSignalsAccess(Activity) esegue un controllo di blocco degli indicatori di età attuali dell'utente e dello stato di condivisione degli indicatori di età.
  • Dopo aver chiamato requestAgeSignalsAccess(Activity), Play mostra un prompt in-app integrato solo per gli utenti non supervisionati. I genitori degli utenti supervisionati possono scegliere di condividere l'età del figlio gestendo le impostazioni di condivisione dell'età nell'app Family Link.
  • Se l'utente chiude o rifiuta la condivisione dell'età, il prompt in-app verrà mostrato alcune volte prima di essere eliminato.
  • Il metodo checkAgeSignals() recupera il valore dei segnali di età nella risposta dell'API. Questo metodo restituisce ageRangeSource, ageUpper, ageLower e altri valori di variazione significativa.
Indietro
Utilizzare gli indicatori dell'età
Avanti
Comprendere le risposte dell'API Age Signals