Demander des signaux d'âge

Ce document explique comment demander des signaux d'âge à l'aide de l'API Play Age Signals.

Le SDK Play Age Signals 0.0.4 introduit une architecture à deux fonctions conçue pour simplifier les demandes de signaux d'âge et prendre en charge notre modèle basé sur le choix utilisateur. Pour demander des signaux d'âge, suivez ce workflow de haut niveau :

Appelez la méthode requestAgeSignalsAccess(Activity), qui renvoie ageSignalsStatus. La valeur de ageSignalsStatus peut être SHARED, NOT_SHARED ou VERIFICATION_REQUIRED.

  • Si ageSignalsStatus == NOT_SHARED : votre application ne recevra pas de signaux d'âge dans la réponse de l'API.
  • Si ageSignalsStatus == SHARED : appelez la méthode checkAgeSignals(). Si l'utilisateur ou le parent a décidé de partager les signaux d'âge, vous les recevez dans la réponse de l'API et vous pouvez décider comment gérer cette réponse.
  • Si ageSignalsStatus == VERIFICATION_REQUIRED : l'âge de l'utilisateur est inconnu et il se trouve dans une juridiction ou une région où la validation de l'âge et le partage des signaux d'âge sont obligatoires. Pour obtenir un signal d'âge de Google Play dans ces régions, demandez à l'utilisateur de se rendre sur le Play Store pour résoudre son problème.

La méthode requestAgeSignalsAccess(Activity) renvoie différentes valeurs selon que le partage obligatoire de l'âge s'applique ou non dans une région :

  • Pour les utilisateurs éligibles dans les États américains dont les lois exigent que les magasins d'applications fournissent des informations d'âge validées aux développeurs, l'invite dans l'application n'est pas déclenchée. Les utilisateurs seront plutôt invités à valider leur âge ou à configurer la supervision lorsqu'ils se rendront dans l'application Play Store. Utilisez la valeur de ageSignalsStatus pour déterminer l'état de validation :
  • Pour les utilisateurs d'autres régions où le partage de l'âge dépend du choix de l'utilisateur ou du parent :
    • Si le paramètre de l'utilisateur est Demander avant de partager, l'invite dans l'application est affichée. Si l'utilisateur accepte de partager son âge, la valeur de ageSignalsStatus est SHARED. Sinon, elle est NOT_SHARED.
    • Si le paramètre de l'utilisateur est Toujours partager, l'invite dans l'application ne s'affiche pas et la valeur de ageSignalsStatus est SHARED.
    • Si le paramètre de l'utilisateur est Ne jamais partager, l'invite dans l'application ne s'affiche pas et la valeur de ageSignalsStatus est NOT_SHARED.
    • Pour les utilisateurs supervisés, les parents peuvent choisir de partager l'âge de leur enfant dans les paramètres de l'application Family Link. Si les parents choisissent de partager l' âge, la valeur de ageSignalsStatus sera SHARED. Sinon, elle sera NOT_SHARED.

L'image suivante montre la configuration de la tranche d'âge Demander avant de partager dans les paramètres Play.

Menu des paramètres Google Play affichant les options de partage de l'âge : "Demander avant de partager", "Toujours partager" et "Ne jamais partager"
Figure 1. Gérer le partage de l'âge dans les paramètres Play

L'image suivante montre la demande de partage de la tranche d'âge dans l'application qui s'affiche pour les utilisateurs lorsque l'âge est demandé via l'API et que leur paramètre est Demander avant de partager.

Boîte de dialogue de recueil du consentement dans l'application invitant l'utilisateur à partager sa tranche d'âge avec l'application.
Figure 2. Demande de partage de la tranche d'âge dans l'application

L'image suivante montre comment l'utilisateur peut activer ou désactiver le partage de l'âge pour une application spécifique.

Boîte de dialogue des paramètres d'une application spécifique affichant un bouton bascule permettant d'activer ou de désactiver le partage de la tranche d'âge
Figure 3 Activer ou désactiver le partage de l'âge pour une application spécifique

L'exemple suivant montre comment demander des signaux d'âge :

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

Points clés concernant le code

  • La méthode requestAgeSignalsAccess(Activity) effectue une vérification bloquante des signaux d'âge actuels de l'utilisateur et de l'état de partage des signaux d'âge.
  • Après avoir appelé requestAgeSignalsAccess(Activity), Play n'affiche une invite intégrée dans l'application que pour les utilisateurs non supervisés. Les parents d'utilisateurs supervisés peuvent choisir de partager l'âge de leur enfant en gérant les paramètres de partage de l'âge dans l'application Family Link.
  • Si l'utilisateur ignore ou refuse le partage de l'âge, l'invite dans l'application s'affiche plusieurs fois avant d'être supprimée.
  • La méthode checkAgeSignals() obtient la valeur des signaux d'âge dans la réponse de l'API. Cette méthode renvoie ageRangeSource, ageUpper, ageLower et d'autres valeurs de modification importantes.