Żądanie sygnałów dotyczących wieku

W tym dokumencie opisujemy, jak przesyłać żądania sygnałów dotyczących wieku za pomocą interfejsu Play Age Signals API.

Pakiet SDK Play Age Signals w wersji 0.0.4 wprowadza architekturę dwufunkcyjną, która upraszcza wysyłanie żądań sygnałów wieku i obsługuje nasz model oparty na wyborach użytkowników. Aby poprosić o sygnały dotyczące wieku, wykonaj te czynności:

Wywołaj metodę requestAgeSignalsAccess(Activity), która zwraca ageSignalsStatus. Wartość ageSignalsStatus może wynosić SHARED, NOT_SHARED lub VERIFICATION_REQUIRED.

  • Jeśli ageSignalsStatus == NOT_SHARED: w odpowiedzi interfejsu API nie otrzymasz sygnałów dotyczących wieku.
  • Jeśli ageSignalsStatus == SHARED: wywołaj metodę checkAgeSignals(). Jeśli użytkownik lub rodzic zdecyduje się udostępnić sygnały dotyczące wieku, otrzymasz je w odpowiedzi interfejsu API i możesz zdecydować, jak ją przetworzyć.
  • Jeśli ageSignalsStatus == VERIFICATION_REQUIRED: wiek użytkownika jest nieznany, a użytkownik znajduje się w odpowiedniej jurysdykcji lub regionie, w którym weryfikacja wieku i udostępnianie sygnałów dotyczących wieku są obowiązkowe. Aby uzyskać sygnał dotyczący wieku z Google Play w tych regionach, poproś użytkownika o odwiedzenie Sklepu Play w celu rozwiązania problemu ze statusem.

Metoda requestAgeSignalsAccess(Activity) zwraca różne wartości w zależności od tego, czy w danym regionie obowiązuje obowiązkowe udostępnianie wieku:

  • W przypadku kwalifikujących się użytkowników w stanach USA, w których obowiązują przepisy wymagające od sklepów z aplikacjami przekazywania deweloperom zweryfikowanych informacji o wieku, nie jest wyświetlany komunikat w aplikacji. Zamiast tego użytkownicy będą proszeni o weryfikację lub skonfigurowanie nadzoru, gdy otworzą aplikację Sklep Play. Aby określić stan weryfikacji, użyj wartości ageSignalsStatus:
  • W przypadku użytkowników z innych regionów, w których udostępnianie wieku zależy od wyboru użytkownika lub rodzica:
    • Jeśli użytkownik ma ustawienie Pytaj przed udostępnieniem, wyświetli się prośba w aplikacji. Jeśli użytkownik zgodzi się udostępnić swój wiek, wartość ageSignalsStatus będzie wynosić SHARED, w przeciwnym razie – NOT_SHARED.
    • Jeśli użytkownik ma ustawienie Zawsze udostępniaj, w aplikacji nie wyświetla się prośba o udostępnianie, a wartość ageSignalsStatus to SHARED.
    • Jeśli użytkownik ma ustawienie Nigdy nie udostępniaj, prośba w aplikacji nie jest wyświetlana, a wartość ageSignalsStatus to NOT_SHARED.
    • W przypadku nadzorowanych użytkowników rodzice mogą udostępniać wiek dziecka w ustawieniach aplikacji Family Link. Jeśli rodzice zdecydują się udostępnić wiek, wartość ageSignalsStatus będzie wynosić SHARED, w przeciwnym razie będzie to NOT_SHARED.

Obraz poniżej przedstawia konfigurację przedziału wiekowego dla ustawienia Pytaj przed udostępnieniem w ustawieniach Google Play.

Menu ustawień Google Play z opcjami udostępniania wieku: Pytaj przed udostępnieniem, Zawsze udostępniaj i Nigdy nie udostępniaj
Rysunek 1. Zarządzaj udostępnianiem wieku w ustawieniach Google Play.

Obraz poniżej przedstawia wyświetlane w aplikacji żądanie udostępnienia przedziału wiekowego, które pojawia się, gdy wiek jest wymagany przez interfejs API, a ustawienie użytkownika to Zapytaj przed udostępnieniem.

W aplikacji wyświetla się okno z prośbą o zgodę na udostępnienie przedziału wiekowego.
Rysunek 2. Prośba o udostępnienie przedziału wiekowego w aplikacji.

Obraz poniżej pokazuje, jak użytkownik może włączyć lub wyłączyć udostępnianie wieku w przypadku konkretnej aplikacji.

Okno ustawień konkretnej aplikacji z przełącznikiem umożliwiającym włączenie lub wyłączenie udostępniania przedziału wiekowego
Rysunek 3. Włącz lub wyłącz udostępnianie wieku w przypadku konkretnej aplikacji.

Ten przykład pokazuje, jak wysłać żądanie o sygnały dotyczące wieku:

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

Najważniejsze informacje o kodzie

  • Metoda requestAgeSignalsAccess(Activity) przeprowadza blokujące sprawdzenie bieżących sygnałów dotyczących wieku użytkownika i stanu udostępniania sygnałów dotyczących wieku.
  • Po wywołaniu funkcji requestAgeSignalsAccess(Activity) Google Play wyświetla wbudowany w aplikacji komunikat tylko użytkownikom bez nadzoru. Rodzice nadzorowanych użytkowników mogą udostępniać wiek dziecka, zarządzając ustawieniami udostępniania wieku w aplikacji Family Link.
  • Jeśli użytkownik odrzuci udostępnianie wieku, w aplikacji kilka razy pojawi się prośba o to, zanim zostanie wyłączona.
  • Metoda checkAgeSignals() pobiera wartość sygnałów dotyczących wieku w odpowiedzi interfejsu API. Ta metoda zwraca wartości ageRangeSource, ageUpper, ageLower i inne wartości istotnych zmian.