Matchmaking API

Hướng dẫn về Health Connect Matchmaking API.

Tổng quan

Matchmaking API cho phép ứng dụng của bạn khám phá những ứng dụng và thiết bị khác có thể ghi dữ liệu sức khoẻ mà ứng dụng của bạn có quyền đọc. Điều này giúp người dùng kết nối các nguồn dữ liệu yêu thích của họ với ứng dụng của bạn một cách dễ dàng hơn.

Màn hình Matchmaking (Kết nối) sẽ phát hiện các ứng dụng và thiết bị tương thích với Health Connect. Sau đó, Google Play sẽ tham chiếu chéo các quyền đọc bắt buộc của ứng dụng với khả năng ghi của những ứng dụng và thiết bị đó. Màn hình hiển thị các ứng dụng và thiết bị đã khai báo nhưng chưa được cấp quyền ghi cho ít nhất một trong các loại bản ghi được chỉ định mà ứng dụng của bạn được phép đọc.

Trước khi bắt đầu

Hướng dẫn này giả định rằng bạn đã định cấu hình Health Connect trong ứng dụng và có một phiên bản HealthConnectClient.

Thiết lập bản thử nghiệm beta

Matchmaking API có trong bản cập nhật Health Connect đang dần được triển khai cho các thiết bị sản xuất và dự kiến sẽ có mặt trên 100% thiết bị vào đầu tháng 6 năm 2026. Để kiểm thử các tính năng tìm kiếm người chơi trước khi bản cập nhật này ra mắt rộng rãi, hãy đăng ký thiết bị thử nghiệm của bạn vào Chương trình Thử nghiệm Android để được tiếp cận sớm.

Kiểm tra phạm vi cung cấp của Health Connect

Trước khi cố gắng sử dụng Health Connect, ứng dụng của bạn phải xác minh rằng Health Connect có trên thiết bị của người dùng. Health Connect có thể chưa được cài đặt trên thiết bị của người dùng hoặc có thể bị vô hiệu hoá.

Sử dụng HealthConnectClient.getSdkStatus() để kiểm tra tình trạng còn hàng. Nếu Health Connect không hoạt động, hãy nhắc người dùng cài đặt hoặc cập nhật Health Connect qua Cửa hàng Google Play.

Kiểm tra phạm vi cung cấp của các tính năng

Để xác định xem thiết bị của người dùng có hỗ trợ tính năng so khớp trên Health Connect hay không, hãy kiểm tra xem FEATURE_MATCHMAKING có sẵn hay không:

if (healthConnectClient
    .features
    .getFeatureStatus(
    HealthConnectFeatures.FEATURE_MATCHMAKING
    ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

// Feature is available
} else {
// Feature isn't available
}

Triển khai

Quy trình mai mối được khởi chạy bằng MatchmakingRequest. Yêu cầu này xác định những loại bản ghi mà bạn muốn ứng dụng của mình thu thập, đồng thời cho phép bạn đưa vào hoặc loại trừ các nguồn dữ liệu cụ thể như ứng dụng hoặc thiết bị:

• recordTypes: Một nhóm các lớp Record, chẳng hạn như StepsRecord::class. Nếu trống, quy trình sẽ xem xét tất cả các loại bản ghi mà ứng dụng của bạn có quyền đọc.
• includedDataSources: Một tập hợp các đối tượng DataOrigin để chỉ bao gồm.
• excludedDataSources: Một tập hợp các đối tượng DataOrigin cần loại trừ.

Hãy làm theo các bước sau để tích hợp Matchmaking API vào ứng dụng của bạn.

Kiểm tra xem có thể ghép trận đấu hay không

Trước khi hiện một điểm truy cập ghép trận đấu, hãy dùng checkIfMatchmakingIsPossible() để xác định xem có ứng dụng hoặc thiết bị phù hợp nào cho các loại bản ghi được yêu cầu hay không:

suspend fun checkMatchmakingPossible(healthConnectClient: HealthConnectClient) {
    val request = MatchmakingRequest(recordTypes = setOf(StepsRecord::class))
    val response = healthConnectClient.checkIfMatchmakingIsPossible(request)

    if (response.isMatchmakingPossible) {
        // Relevant apps or devices found. Show entry point to launch flow.
    } else {
        // Handle case where no new data sources are available
    }
}

Bạn nên thường xuyên kiểm tra xem có thể ghép trận đấu hay không. Sau này, người dùng có thể cài đặt thêm các ứng dụng hoặc kết nối các thiết bị có kiểu dữ liệu tương thích lẫn nhau. Một phương pháp phổ biến là kiểm tra mỗi khi ứng dụng của bạn khởi động. Nếu phương thức này trả về true, hãy hiện một điểm truy cập để khởi chạy quy trình mai mối.

Khởi chạy quy trình Matchmaking

Nếu có thể so khớp, hãy dùng createMatchmakingIntent() để nhận Intent nhằm chạy quy trình Health Connect, sau đó chạy quy trình này bằng Activity Result API:

// Create the matchmaking launcher
val matchmakingLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // Matchmaking finished successfully.
        // User successfully granted at least one permission.
    } else {
        // User canceled flow or didn't grant permissions.
    }
}

fun launchMatchmaking(healthConnectClient: HealthConnectClient) {
    val request = MatchmakingRequest(recordTypes = setOf(StepsRecord::class))
    val intent = healthConnectClient.createMatchmakingIntent(request)
    matchmakingLauncher.launch(intent)
}

Khi khởi chạy ý định này, Health Connect sẽ hiển thị một màn hình nơi người dùng có thể xem các ứng dụng và thiết bị tương thích, đồng thời chọn kết nối chúng để chia sẻ dữ liệu với ứng dụng của bạn.