Meminta sinyal usia

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

SDK Sinyal Usia Play 0.0.4 memperkenalkan arsitektur dua fungsi yang dirancang untuk menyederhanakan permintaan sinyal usia dan mendukung model berbasis pilihan pengguna kami. 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 atau wilayah hukum yang berlaku di mana verifikasi usia dan berbagi sinyal usia bersifat wajib. Untuk mendapatkan sinyal usia dari Google Play di wilayah ini, minta pengguna membuka Google Play Store untuk menyelesaikan status mereka.

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 AS 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 melakukan verifikasi atau menyiapkan pengawasan saat mereka membuka aplikasi Google Play Store. Gunakan nilai ageSignalsStatus untuk menentukan status verifikasi:
  • Untuk pengguna di wilayah lain yang berbagi usia berdasarkan pilihan pengguna atau orang tua:
    • Jika setelan pengguna adalah Tanya sebelum berbagi, perintah 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 ditampilkan, dan nilai ageSignalsStatus adalah SHARED.
    • Jika setelan pengguna adalah Jangan Pernah Bagikan, dialog dalam aplikasi tidak 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, nilai tersebut akan menjadi NOT_SHARED.

Gambar berikut menunjukkan konfigurasi rentang usia Tanya sebelum berbagi di setelan Play.

Menu setelan Google Play yang menampilkan opsi untuk berbagi usia: Tanya sebelum berbagi, Selalu bagikan, dan Jangan pernah bagikan
Gambar 1. Mengelola berbagi usia di setelan Play.

Gambar berikut menunjukkan permintaan berbagi rentang usia dalam aplikasi yang ditampilkan kepada pengguna saat usia diminta melalui API dan setelan mereka adalah Tanya sebelum berbagi.

Dialog izin dalam aplikasi yang meminta pengguna untuk membagikan rentang usia mereka ke aplikasi.
Gambar 2. Permintaan berbagi rentang usia dalam aplikasi.

Gambar berikut menunjukkan cara pengguna dapat mengaktifkan atau menonaktifkan berbagi usia untuk aplikasi tertentu.

Dialog setelan untuk aplikasi tertentu yang menampilkan tombol pengalih untuk mengaktifkan atau menonaktifkan berbagi rentang usia
Gambar 3. Mengaktifkan atau menonaktifkan berbagi usia untuk aplikasi tertentu.

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 penting tentang kode

  • Metode requestAgeSignalsAccess(Activity) melakukan pemeriksaan pemblokiran terhadap sinyal usia pengguna saat ini dan status berbagi sinyal usia.
  • Setelah Anda memanggil requestAgeSignalsAccess(Activity), Play akan menampilkan dialog dalam aplikasi bawaan hanya untuk pengguna yang tidak diawasi. 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, perintah dalam aplikasi akan ditampilkan beberapa kali sebelum perintah tersebut dihentikan.
  • Metode checkAgeSignals() mendapatkan nilai sinyal usia dalam respons API. Metode ini menampilkan ageRangeSource, ageUpper, ageLower, dan nilai perubahan signifikan lainnya.