Meminta sinyal usia

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

SDK Play Age Signals 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 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 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 Amerika Serikat dengan 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 membagikan, dialog dalam aplikasi akan ditampilkan. Jika pengguna setuju untuk membagikan usianya, nilai ageSignalsStatus adalah SHARED; jika tidak, NOT_SHARED.
    • Jika setelan pengguna adalah Always Share, dialog dalam aplikasi tidak akan ditampilkan, dan nilai ageSignalsStatus adalah SHARED.
    • Jika setelan pengguna adalah Never Share, 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, nilainya akan menjadi NOT_SHARED.

Untuk memahami cara kerja berbagi usia di Google Play, termasuk perintah 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
            }
        }
        .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 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 dari 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.