Yêu cầu tín hiệu về độ tuổi

Tài liệu này mô tả cách yêu cầu tín hiệu về độ tuổi bằng cách sử dụng Play Age Signals API.

SDK Play Age Signals 0.0.4 giới thiệu một cấu trúc gồm 2 hàm được thiết kế để đơn giản hoá các yêu cầu về tín hiệu độ tuổi và hỗ trợ mô hình dựa trên sự lựa chọn của người dùng. Để yêu cầu tín hiệu về độ tuổi, hãy sử dụng quy trình công việc tổng thể sau:

Gọi phương thức requestAgeSignalsAccess(Activity). Phương thức này sẽ trả về ageSignalsStatus. Giá trị của ageSignalsStatus có thể là SHARED, NOT_SHARED hoặc VERIFICATION_REQUIRED.

  • Nếu ageSignalsStatus == NOT_SHARED: Ứng dụng của bạn sẽ không nhận được tín hiệu về độ tuổi trong phản hồi API.
  • Nếu ageSignalsStatus == SHARED: Gọi phương thức checkAgeSignals(). Nếu người dùng hoặc cha mẹ đã quyết định chia sẻ tín hiệu về độ tuổi, bạn sẽ nhận được tín hiệu về độ tuổi trong phản hồi của API và bạn có thể quyết định cách xử lý phản hồi đó.
  • Nếu ageSignalsStatus == VERIFICATION_REQUIRED: Độ tuổi của người dùng là không xác định và người dùng ở một khu vực tài phán hoặc khu vực áp dụng bắt buộc phải xác minh độ tuổi và chia sẻ tín hiệu về độ tuổi. Để nhận tín hiệu về độ tuổi từ Google Play ở những khu vực này, hãy yêu cầu người dùng truy cập vào Cửa hàng Play để giải quyết trạng thái của họ.

Phương thức requestAgeSignalsAccess(Activity) trả về các giá trị khác nhau tuỳ thuộc vào việc có áp dụng chế độ chia sẻ độ tuổi bắt buộc ở một khu vực hay không:

  • Đối với những người dùng đủ điều kiện ở các tiểu bang của Hoa Kỳ có luật yêu cầu cửa hàng ứng dụng cung cấp thông tin đã xác minh về độ tuổi cho nhà phát triển, lời nhắc trong ứng dụng sẽ không xuất hiện. Thay vào đó, người dùng sẽ được yêu cầu xác minh hoặc thiết lập chế độ giám sát khi truy cập vào ứng dụng Cửa hàng Play. Hãy sử dụng giá trị của ageSignalsStatus để xác định trạng thái xác minh:
  • Đối với người dùng ở những khu vực khác mà việc chia sẻ độ tuổi dựa trên lựa chọn của người dùng hoặc cha mẹ:
    • Nếu người dùng đặt chế độ Hỏi trước khi chia sẻ, thì lời nhắc trong ứng dụng sẽ xuất hiện. Nếu người dùng đồng ý chia sẻ độ tuổi, giá trị của ageSignalsStatusSHARED; nếu không, giá trị này là NOT_SHARED.
    • Nếu chế độ cài đặt của người dùng là Luôn chia sẻ, thì lời nhắc trong ứng dụng sẽ không xuất hiện và giá trị của ageSignalsStatusSHARED.
    • Nếu chế độ cài đặt của người dùng là Không bao giờ chia sẻ, thì lời nhắc trong ứng dụng sẽ không xuất hiện và giá trị của ageSignalsStatusNOT_SHARED.
    • Đối với người dùng được giám sát, cha mẹ có thể chọn chia sẻ độ tuổi của trẻ trong phần cài đặt ứng dụng Family Link. Nếu cha mẹ chọn chia sẻ độ tuổi, giá trị của ageSignalsStatus sẽ là SHARED, nếu không thì giá trị sẽ là NOT_SHARED.

Hình ảnh sau đây cho thấy chế độ cài đặt độ tuổi Hỏi trước khi chia sẻ trong phần cài đặt Play.

Trình đơn cài đặt của Google Play có các lựa chọn chia sẻ độ tuổi: Hỏi trước khi chia sẻ, Luôn chia sẻ và Không bao giờ chia sẻ
Hình 1. Quản lý chế độ chia sẻ độ tuổi trong phần cài đặt Play.

Hình ảnh sau đây cho thấy yêu cầu chia sẻ độ tuổi trong ứng dụng mà người dùng nhìn thấy khi độ tuổi được yêu cầu thông qua API và chế độ cài đặt của họ là Hỏi trước khi chia sẻ.

Hộp thoại đồng ý trong ứng dụng nhắc người dùng chia sẻ độ tuổi của họ với ứng dụng.
Hình 2. Yêu cầu chia sẻ độ tuổi trong ứng dụng.

Hình ảnh sau đây cho thấy cách người dùng có thể bật hoặc tắt tính năng chia sẻ độ tuổi cho một ứng dụng cụ thể.

Hộp thoại Cài đặt cho một ứng dụng cụ thể, có nút bật/tắt để bật hoặc tắt tính năng chia sẻ độ tuổi
Hình 3. Bật hoặc tắt tính năng chia sẻ độ tuổi cho một ứng dụng cụ thể.

Ví dụ sau đây cho thấy cách yêu cầu tín hiệu về độ tuổi:

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

Các điểm chính về mã

  • Phương thức requestAgeSignalsAccess(Activity) thực hiện một quy trình kiểm tra chặn các tín hiệu độ tuổi hiện tại của người dùng và trạng thái chia sẻ tín hiệu độ tuổi.
  • Sau khi bạn gọi requestAgeSignalsAccess(Activity), Play sẽ chỉ hiển thị lời nhắc trong ứng dụng tích hợp cho người dùng không được giám sát. Cha mẹ của người dùng được giám sát có thể chọn chia sẻ độ tuổi của trẻ bằng cách quản lý cài đặt cách chia sẻ độ tuổi trong ứng dụng Family Link.
  • Nếu người dùng đóng hoặc từ chối chia sẻ độ tuổi, lời nhắc trong ứng dụng sẽ xuất hiện một vài lần trước khi bị ẩn.
  • Phương thức checkAgeSignals() sẽ nhận giá trị tín hiệu về độ tuổi trong phản hồi API. Phương thức này trả về ageRangeSource, ageUpper, ageLower và các giá trị thay đổi đáng kể khác.