Matchmaking API

ヘルスコネクトの Matchmaking API のガイド。

概要

Matchmaking API を使用すると、アプリが読み取り権限を持つヘルスデータを書き込むことができる他のアプリやデバイスをアプリで検出できます。これにより、ユーザーは好みのデータソースをアプリに簡単に接続できます。

Matchmaking 画面では、ヘルスコネクトに対応したアプリとデバイスが検出されます。次に、アプリに必要な読み取り権限と、それらのアプリとデバイスの書き込み機能を相互参照します。この画面には、アプリが読み取りを許可されている指定のレコードタイプの少なくとも 1 つについて、書き込み権限を宣言しているがまだ付与されていないアプリとデバイスが表示されます。

始める前に

このガイドは、アプリでヘルスコネクトをすでに 構成済みで 、HealthConnectClient のインスタンスを使用できることを前提としています。

ベータ版の設定

Matchmaking API は、ヘルスコネクトのアップデートを通じて利用できます。このアップデートは、本番環境デバイスに段階的にロールアウトされ、2026 年 6 月上旬までに 100% のデバイスで利用可能になる予定です。この アップデートが広く利用可能になる前に照合機能をテストするには、テストデバイスを Android ベータ版プログラムに登録して早期アクセスしてください。

ヘルスコネクトを利用できるか確認する

ヘルスコネクト アプリを使用する前に、ユーザーのデバイスでヘルスコネクトが利用可能であることを確認する必要があります。ヘルスコネクトがユーザーのデバイスにインストールされていない場合や、無効になっている可能性があります。

HealthConnectClient.getSdkStatus() を使用して、 利用可能かどうかを確認します。ヘルスコネクトが利用できない場合は、Google Play ストアからヘルスコネクトをインストールまたは更新するようユーザーに促します。

使用できる機能を確認する

ユーザーのデバイスがヘルスコネクトでの照合をサポートしているかどうかを判断するには、FEATURE_MATCHMAKING が利用可能かどうかを確認します。

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

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

実装

照合フローは MatchmakingRequest を使用して起動します。このリクエストでは、アプリが収集するレコードタイプを定義し、アプリやデバイスなどの特定のデータソースを含めるか除外するかを指定できます。

• recordTypes: Record クラスのセット (例: StepsRecord::class)。空の場合、フローはアプリが読み取り権限を持つすべてのレコードタイプを考慮します。
• includedDataSources: 除外する DataOrigin オブジェクトのセット。
• excludedDataSources: 除外する DataOrigin オブジェクトのセット。

Matchmaking API をアプリに統合するには、次の手順を行います。

照合が可能かどうかを確認する

照合のエントリ ポイントを表示する前に、checkIfMatchmakingIsPossible() を使用して、リクエストされたレコードタイプに関連する照合アプリまたはデバイスがあるかどうかを確認します。

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

照合が可能かどうかを継続的に確認することをおすすめします。 ユーザーが後で追加のアプリをインストールしたり、相互に互換性のあるデータ型を持つデバイスを接続したりする可能性があります。一般的な方法として、アプリが起動するたびに確認します。true が返された場合は、マッチメイキング フローを起動するエントリ ポイントを表示します。

照合フローを起動する

照合が可能な場合は、createMatchmakingIntent() を使用して、ヘルスコネクト フローを起動する Intent を取得し、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)
}

このインテントを起動すると、ヘルスコネクトに、互換性のあるアプリとデバイスを表示する画面が表示されます。ユーザーは、アプリとデータを共有するために、それらを接続することを選択できます。