Matchmaking API

Hướng dẫn về API Matchmaking (Kết nối) của Health Connect.

Tổng quan

API Matchmaking (Kết nối) cho phép ứng dụng của bạn khám phá các ứ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 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ẽ khám phá các ứng dụng và thiết bị tương thích với Health Connect. Sau đó, màn hình này sẽ đối chiếu 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 này sẽ hiện các ứng dụng và thiết bị đã khai báo nhưng chưa 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 thực thể HealthConnectClient khả dụng.

Thiết lập phiên bản beta

API Matchmaking (Kết nối) được cung cấp thông qua bản cập nhật cho Health Connect. Bản cập nhật này đang dần được triển khai cho các thiết bị chính thức 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 được cung cấp 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. Có thể Health Connect chưa được cài đặt trên thiết bị của người dùng hoặc đã bị tắt.

Hãy dùng HealthConnectClient.getSdkStatus() để kiểm tra phạm vi cung cấp. Nếu Health Connect không có, hãy nhắc người dùng cài đặt hoặc cập nhật Health Connect từ 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 kết nối trên Health Connect hay không, hãy kiểm tra phạm vi cung cấp của FEATURE_MATCHMAKING:

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 kết nối được khởi chạy bằng cách sử dụ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 và cho phép bạn đưa vào hoặc loại trừ các nguồn dữ liệu cụ thể, chẳng hạn như ứng dụng hoặc thiết bị:

• recordTypes: Một tập hợp 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ỉ đưa vào.
• excludedDataSources: Một tập hợp các đối tượng DataOrigin để loại trừ.

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

Kiểm tra xem có thể kết nối hay không

Trước khi hiện điểm truy cập kết nối, 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ể kết nối hay không. Sau này, người dùng có thể cài đặt thêm ứng dụng hoặc kết nối các thiết bị có loại dữ liệu tương thích với 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 điểm truy cập để khởi chạy quy trình kết nối.

Khởi chạy quy trình kết nối

Nếu có thể kết nối, hãy dùng createMatchmakingIntent() để lấy Intent nhằm khởi chạy quy trình Health Connect, sau đó khởi chạy quy trình này bằng API Kết quả hoạt động:

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

Bằng cách khởi chạy ý định này, Health Connect sẽ hiện một màn hình để 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 các ứng dụng và thiết bị đó để chia sẻ dữ liệu với ứng dụng của bạn.