Meminta sinyal usia

Dokumen ini menjelaskan cara meminta sinyal usia menggunakan Play Age Signals API.

Play Age Signals 0.0.4 SDK memperkenalkan arsitektur dua fungsi yang dirancang untuk menyederhanakan permintaan sinyal usia dan mendukung model berbasis pilihan pengguna. Untuk meminta sinyal usia, gunakan alur kerja tingkat tinggi ini:

Panggil metode requestAgeSignalsAccess(Activity), yang menampilkan ageSignalsStatus. Nilai ageSignalsStatus dapat berupa SHARED, NOT_SHARED, atau VERIFICATION_REQUIRED.

  • Jika ageSignalsStatus == NOT_SHARED: Aplikasi Anda tidak akan mendapatkan sinyal usia dalam respons API.
  • Jika ageSignalsStatus == SHARED: Panggil metode checkAgeSignals(). Jika pengguna atau orang tua telah memutuskan untuk membagikan sinyal usia, Anda akan menerima sinyal usia sebagai bagian dari respons API, dan Anda dapat memutuskan cara menangani respons tersebut.
  • Jika ageSignalsStatus == VERIFICATION_REQUIRED: Usia pengguna tidak diketahui dan pengguna berada di wilayah hukum atau wilayah yang berlaku tempat verifikasi usia dan berbagi sinyal usia bersifat wajib. Untuk mendapatkan sinyal usia dari Google Play di wilayah ini, minta pengguna untuk membuka Google Play Store guna menyelesaikan statusnya.

Metode requestAgeSignalsAccess(Activity) menampilkan nilai yang berbeda, bergantung pada apakah berbagi usia wajib berlaku di suatu wilayah:

  • Untuk pengguna yang memenuhi syarat di negara bagian Amerika Serikat yang memiliki hukum yang mewajibkan app store memberikan informasi usia terverifikasi kepada developer, dialog dalam aplikasi tidak akan dipicu. Sebagai gantinya, pengguna akan diminta untuk memverifikasi atau menyiapkan pengawasan saat mereka membuka aplikasi Google Play Store. Gunakan nilai ageSignalsStatus untuk menentukan status verifikasi:
  • Untuk pengguna di wilayah lain tempat berbagi usia didasarkan pada pilihan pengguna atau orang tua:
    • Jika setelan pengguna adalah Tanya sebelum membagikan, dialog dalam aplikasi akan ditampilkan. Jika pengguna setuju untuk membagikan usianya, nilai ageSignalsStatus adalah SHARED; jika tidak, NOT_SHARED.
    • Jika setelan pengguna adalah Selalu Bagikan, dialog dalam aplikasi tidak akan ditampilkan, dan nilai ageSignalsStatus adalah SHARED.
    • Jika setelan pengguna adalah Jangan Pernah Bagikan, dialog dalam aplikasi tidak akan ditampilkan, dan nilai ageSignalsStatus adalah NOT_SHARED.
    • Untuk pengguna yang diawasi, orang tua dapat memilih untuk membagikan usia anak mereka di setelan aplikasi Family Link. Jika orang tua memilih untuk membagikan usia, nilai ageSignalsStatus akan menjadi SHARED, jika tidak, akan menjadi NOT_SHARED.

Untuk memahami cara kerja berbagi usia di Google Play, termasuk dialog dalam aplikasi dan setelan berbagi rentang usia, lihat Berbagi rentang usia di Google Play.

Contoh berikut menunjukkan cara meminta sinyal usia:

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

Poin-poin penting tentang kode

  • Metode requestAgeSignalsAccess(Activity) melakukan pemeriksaan pemblokiran terhadap sinyal usia dan status berbagi sinyal usia pengguna saat ini.
  • Setelah Anda memanggil requestAgeSignalsAccess(Activity), Play akan menampilkan dialog dalam aplikasi bawaan hanya untuk pengguna tanpa pengawasan. Orang tua pengguna yang diawasi dapat memilih untuk membagikan usia anak mereka dengan mengelola setelan berbagi usia di aplikasi Family Link.
  • Jika pengguna menutup atau menolak berbagi usia, dialog dalam aplikasi akan ditampilkan beberapa kali sebelum dialog tersebut disembunyikan.
  • Metode checkAgeSignals() mendapatkan nilai sinyal usia dalam respons API. Metode ini menampilkan ageRangeSource, ageUpper, ageLower, dan nilai perubahan signifikan lainnya.