Solicitar indicadores de idade

Neste documento, descrevemos como solicitar indicadores de idade usando a API Play Age Signals.

Para solicitar indicadores de idade, use este fluxo de trabalho de alto nível:

  1. (Opcional) Chame o método getApplicableAgeFeatures(), que retorna ApplicableAgeFeaturesResult. Chame features() no resultado para verificar o conjunto de recursos relacionados à idade aplicáveis ao usuário. Isso retorna:

    • MANDATORY_SHARING: indica que o compartilhamento obrigatório de indicadores de idade se aplica ao usuário. Isso é retornado apenas para usuários em regiões com leis que exigem que as app stores compartilhem informações de idade. Se a confirmação de idade também for necessária para esse usuário, o Google Play vai cuidar disso, e a API vai retornar as respostas de acordo.

    • Um conjunto vazio ([]): retornado para todos os outros usuários.

  2. Chame o método requestAgeSignalsAccess(Activity), que retorna ageSignalsStatus. O valor de ageSignalsStatus pode ser SHARED, NOT_SHARED ou VERIFICATION_REQUIRED.

    • Se for ageSignalsStatus == NOT_SHARED: seu app não vai receber indicadores de idade na resposta da API.

    • Se ageSignalsStatus == SHARED: chame o método checkAgeSignals(). Se o usuário ou o familiar responsável decidir compartilhar os indicadores de idade, você vai receber esses indicadores como parte da resposta da API e poderá decidir como lidar com ela.

    • Se ageSignalsStatus == VERIFICATION_REQUIRED: a idade do usuário não foi confirmada, e ele está em uma jurisdição ou região aplicável em que a confirmação de idade e o compartilhamento de indicadores de idade são obrigatórios. Para obter um indicador de idade do Google Play nessas regiões, peça ao usuário para acessar a Google Play Store e resolver o status.

O método requestAgeSignalsAccess(Activity) retorna valores diferentes dependendo se o compartilhamento obrigatório de idade é aplicável em uma região:

  • Para usuários qualificados em estados dos EUA com leis que exigem que as app stores forneçam informações de idade verificadas aos desenvolvedores, a solicitação no app não é acionada. Em vez disso, os usuários vão precisar verificar ou configurar a supervisão quando acessarem o app da Google Play Store. Use o valor de ageSignalsStatus para determinar o status de verificação:
  • Para usuários em outras regiões onde o compartilhamento de idade é baseado na escolha do usuário ou do familiar responsável:
    • Se a configuração do usuário for Perguntar antes de compartilhar, a solicitação no app será mostrada. Se o usuário concordar em compartilhar a idade, o valor de ageSignalsStatus será SHARED. Caso contrário, será NOT_SHARED.
    • Se a configuração do usuário for Sempre compartilhar, a solicitação no app não será mostrada, e o valor de ageSignalsStatus será SHARED.
    • Se a configuração do usuário for Nunca compartilhar, a solicitação no app não será mostrada, e o valor de ageSignalsStatus será NOT_SHARED.
    • Para usuários supervisionados, os familiares responsáveis podem compartilhar a idade da criança nas configurações do app Family Link. Se os pais optarem por compartilhar a idade, o valor de ageSignalsStatus será SHARED. Caso contrário, será NOT_SHARED.

O exemplo a seguir mostra como solicitar indicadores de idade:

Kotlin

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

// (Optional) Check whether mandatory age sharing applies to the user.
ageSignalsManager.getApplicableAgeFeatures(ApplicableAgeFeaturesRequest.builder().build())
    .addOnSuccessListener { featuresResult ->
        if (featuresResult.features().contains(ApplicableAgeFeature.MANDATORY_SHARING)) {
            // Mandatory age sharing applies to the user.
        }
    }

// 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
            }
        }
        .addOnFailureListener { exception ->
            handleAgeSignalsError(exception)
        }
}

Java

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

// (Optional) Check whether mandatory age sharing applies to the user.
ageSignalsManager.getApplicableAgeFeatures(ApplicableAgeFeaturesRequest.builder().build())
    .addOnSuccessListener(featuresResult -> {
        if (featuresResult.features().contains(ApplicableAgeFeature.MANDATORY_SHARING)) {
            // Mandatory age sharing applies to the user.
        }
    });

// 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);
        });
}

Pontos principais sobre o código

  • O método getApplicableAgeFeatures() verifica quais recursos relacionados à idade (como ApplicableAgeFeature.MANDATORY_SHARING) se aplicam ao usuário.
  • O método requestAgeSignalsAccess(Activity) realiza uma verificação de bloqueio dos indicadores de idade atuais do usuário e do status de compartilhamento desses indicadores.
  • Depois que você chamar requestAgeSignalsAccess(Activity), o Google Play vai mostrar uma solicitação integrada no app apenas para usuários não supervisionados. Os familiares responsáveis por usuários supervisionados podem escolher compartilhar a idade da criança ou do adolescente gerenciando as configurações de compartilhamento de idade no app Family Link.
  • Se o usuário dispensar ou recusar o compartilhamento de idade, a solicitação no app será mostrada algumas vezes antes de ser suprimida.
  • O método checkAgeSignals() recebe o valor dos indicadores de idade na resposta da API. Esse método retorna ageRangeSource, ageUpper, ageLower e outros valores de mudança significativa.