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 Play Age Signals API.

SDK Play Age Signals 0.0.4 ra mắt cấu trúc hai hàm được thiết kế để đơn giản hoá các yêu cầu về dấu 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 tổng quan 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 của 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, thì 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: Không xác định được tuổi của người dùng và người dùng ở một khu vực tài phán hoặc khu vực hiện hành, nơi bắt buộc phải xác minh tuổi và chia sẻ tín hiệu về độ tuổi. Để nhận được 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 quy định bắt buộc chia sẻ độ tuổi ở 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 về độ tuổi đã xác minh cho nhà phát triển, lời nhắc trong ứng dụng sẽ không được kích hoạt. 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 họ 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 ở các khu vực khác, nơi 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 chế độ cài đặt của người dùng là 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 của họ, thì giá trị của ageSignalsStatus là SHARED; nếu không, giá trị sẽ 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 ageSignalsStatus là SHARED.
    • 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 ageSignalsStatus là NOT_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 của ứ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.

Để tìm hiểu cách hoạt động của tính năng chia sẻ nhóm tuổi trên Google Play, bao gồm cả lời nhắc trong ứng dụng và chế độ cài đặt cách chia sẻ nhóm tuổi, hãy xem bài viết Chia sẻ nhóm tuổi trên Google Play.

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