エクササイズのルートを追加する

このガイドは、ヘルスコネクトのバージョン 1.1.0-alpha12 に対応しています。

エクササイズのルートを使用すると、関連するエクササイズ アクティビティの GPS ルートを追跡し、ワークアウトのマップを他のアプリと共有できます。

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

ヘルスコネクト アプリを使用する前に、ユーザーのデバイスでヘルスコネクトが利用可能であることを確認する必要があります。ヘルスコネクトは一部のデバイスにおいて、プリインストールされていない場合や、無効になっている場合があります。HealthConnectClient.getSdkStatus() メソッドを使用して、利用可能かどうかを確認できます。

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

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // Optionally redirect to package installer to find a provider, for example:
      val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
      context.startActivity(
        Intent(Intent.ACTION_VIEW).apply {
          setPackage("com.android.vending")
          data = Uri.parse(uriString)
          putExtra("overlay", true)
          putExtra("callerId", context.packageName)
        }
      )
      return
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

getSdkStatus() から返されるステータスに応じて、必要に応じて Google Play ストアからヘルスコネクトをインストールまたは更新するようユーザーに促すことができます。

このガイドでは、ユーザーに権限をリクエストする方法について説明します。また、エクササイズ セッションの一部としてルートデータを書き込む権限をアプリがどのように取得するかについても説明します。

エクササイズのルートの読み取り / 書き込み機能は次のとおりです。

  1. アプリは、エクササイズのルート用の新しい書き込み権限を作成します。
  2. 挿入は、ルートをフィールドとしてエクササイズのセッションを書き込むことで行われます。
  3. 読み取り:
    1. セッション オーナーの場合、セッション読み取りを使用してデータにアクセスします。
    2. サードパーティ製アプリで、ユーザーがルートの 1 回限りの読み取りを許可できるダイアログを表示します。

ユーザーに書き込み権限がなく、ルートが設定されていない場合、ルートは更新されません。

アプリにルート書き込み権限があり、ルートのないセッション オブジェクトを渡してセッションを更新しようとすると、既存のルートが削除されます。

機能の提供状況

ユーザーのデバイスがヘルスコネクトの計画されたエクササイズに対応しているかどうかを判断するには、クライアントで FEATURE_PLANNED_EXERCISE の利用可否を確認します。

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

  // Feature is available
} else {
  // Feature isn't available
}
詳しくは、機能の提供状況を確認するをご覧ください。

必要な権限

エクササイズのルートへのアクセスは、次の権限によって保護されています。

  • android.permission.health.READ_EXERCISE_ROUTES
  • android.permission.health.WRITE_EXERCISE_ROUTE
注: この権限タイプの場合、READ_EXERCISE_ROUTES は複数形ですが、WRITE_EXERCISE_ROUTE は単数形です。

エクササイズのルート機能をアプリに追加するには、まず ExerciseSession データ型の権限をリクエストします。

エクササイズのルートを記述するために宣言する必要がある権限は次のとおりです。

<application>
  <uses-permission
android:name="android.permission.health.WRITE_EXERCISE_ROUTE" />
...
</application>

エクササイズのルートを読み取るには、次の権限をリクエストする必要があります。

<application>
  <uses-permission
android:name="android.permission.health.READ_EXERCISE_ROUTES" />
...
</application>

また、各ルートはエクササイズ セッションに関連付けられているため、エクササイズ権限を宣言する必要があります（1 セッション = 1 ワークアウト）。

権限をリクエストするには、最初にアプリをヘルスコネクトに接続するときに PermissionController.createRequestPermissionResultContract() メソッドを使用します。必要に応じてリクエストする権限は次のとおりです。

  • 健康とフィットネス データ（ルートデータを含む）の読み取り: HealthPermission.getReadPermission(ExerciseSessionRecord::class)
  • 健康とフィットネスに関するデータ（ルートデータを含む）の書き込み: HealthPermission.getWritePermission(ExerciseSessionRecord::class)
  • エクササイズのルートデータの書き込み: HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

ユーザーに権限をリクエストする

クライアント インスタンスを作成した後、アプリはユーザーに権限をリクエストする必要があります。ユーザーがいつでも権限を付与または拒否できるようにする必要があります。

そのためには、必要なデータ型の権限セットを作成します。 まず、セット内の権限が Android マニフェストで宣言されていることを確認します。

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::class)
)

getGrantedPermissions を使用して、アプリが必要な権限をすでに持っているかどうかを確認します。持っていない場合は、 createRequestPermissionResultContract を使用して 権限をリクエストします。ヘルスコネクトの権限画面が表示されます。

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

ユーザーはいつでも権限を付与または取り消すことができるため、アプリは権限を使用するたびに権限を確認し、権限が失われた状況に対応できるように設計する必要があります。

エクササイズ セッション レコードに含まれる情報

各エクササイズ セッション レコードには、次の情報が含まれます。

  • エクササイズのタイプ （サイクリングなど）。
  • エクササイズのルート （ 緯度、経度、高度などの情報を含む）。

サポートされている集計

ExerciseSessionRecord には、次の集計値を使用できます。

使用例

次のコード スニペットは、エクササイズのルートを読み書きする方法を示しています。

エクササイズのルートの読み込み

アプリがバックグラウンドで実行されている場合、他のアプリで作成されたエクササイズのルートデータを読み取ることはできません。

アプリがバックグラウンドで実行され、別のアプリで作成されたエクササイズのルートを読み取ろうとすると、アプリにエクササイズのルートデータへの常に許可 アクセス権がある場合でも、ヘルスコネクトは ExerciseRouteResult.ConsentRequired レスポンスを返します。

このため、ユーザーがアプリの UI を操作しているときに、ユーザーがアプリを積極的に使用している場合に、ルートをリクエストすることを強くおすすめします。

バックグラウンドでの読み取りについて詳しくは、バックグラウンドでの読み取りの例をご覧ください。

次のコード スニペットは、ヘルスコネクトでセッションを読み取り、そのセッションからルートをリクエストする方法を示しています。

private suspend fun readExerciseSessionAndRoute() {
    val client = healthConnectClient ?: return

    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofHours(1))

    val grantedPermissions = client.permissionController.getGrantedPermissions()

    // 1. Verify basic Exercise Session permissions
    if (!grantedPermissions.contains(
            HealthPermission.getReadPermission(ExerciseSessionRecord::class)
        )
    ) {
        return
    }

    // 2. Read the sessions
    val readResponse = client.readRecords(
        ReadRecordsRequest(
            ExerciseSessionRecord::class,
            TimeRangeFilter.between(startTime, endTime)
        )
    )

    val exerciseRecord = readResponse.records.firstOrNull() ?: return
    val recordId = exerciseRecord.metadata.id

    // 3. Read the specific record to check for the route
    val sessionResponse = client.readRecord(ExerciseSessionRecord::class, recordId)

    // 4. Handle the Route Result directly from the response
    when (val routeResult = sessionResponse.record.exerciseRouteResult) {
        is ExerciseRouteResult.Data -> {
            displayExerciseRoute(routeResult.exerciseRoute)
        }
        is ExerciseRouteResult.ConsentRequired -> {
            // Since you are in a Service, you cannot launch ActivityResultLauncher.
            // Send a notification to the user to grant route-specific consent.
            handleConsentRequired(recordId)
        }
        is ExerciseRouteResult.NoData -> Unit
        else -> Unit
    }
}

private fun displayExerciseRoute(route: ExerciseRoute) {
    val locations = route.route.orEmpty()
    for (location in locations) {
        println(location)
    }
}

エクササイズのルートを作成する

次のコードはエクササイズのルートを含むセッションを記録する方法を示しています。

private suspend fun insertExerciseRoute() {
    val client = healthConnectClient ?: return

    val grantedPermissions = client.permissionController.getGrantedPermissions()

    // 1. Verify Session Write Permission
    val hasWriteSession = grantedPermissions.contains(
        HealthPermission.getWritePermission(ExerciseSessionRecord::class)
    )
    if (!hasWriteSession) return

    val sessionStartTime = Instant.now()
    val sessionDuration = Duration.ofMinutes(20)
    val sessionEndTime = sessionStartTime.plus(sessionDuration)

    // 2. Build the route if route-specific write permission is granted
    val hasWriteRoute = grantedPermissions.contains(HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE)

    val exerciseRoute = if (hasWriteRoute) {
        ExerciseRoute(
            listOf(
                ExerciseRoute.Location(
                    time = sessionStartTime,
                    latitude = 6.5483,
                    longitude = 0.5488,
                    horizontalAccuracy = Length.meters(2.0),
                    verticalAccuracy = Length.meters(2.0),
                    altitude = Length.meters(9.0),
                ),
                ExerciseRoute.Location(
                    time = sessionEndTime.minusSeconds(1),
                    latitude = 6.4578,
                    longitude = 0.6577,
                    horizontalAccuracy = Length.meters(2.0),
                    verticalAccuracy = Length.meters(2.0),
                    altitude = Length.meters(9.2),
                )
            )
        )
    } else {
        null
    }

    // 3. Create the session record
    val exerciseSessionRecord = ExerciseSessionRecord(
        startTime = sessionStartTime,
        startZoneOffset = ZoneOffset.UTC,
        endTime = sessionEndTime,
        endZoneOffset = ZoneOffset.UTC,
        exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_BIKING,
        title = "Morning Bike Ride",
        exerciseRoute = exerciseRoute,
        metadata = Metadata(
            device = Device(type = Device.TYPE_PHONE)
        )
    )

    // 4. Insert into Health Connect
    client.insertRecords(listOf(exerciseSessionRecord))
}

エクササイズ セッション

エクササイズ セッションには、ランニングからバドミントンまでさまざまなものがあります。

エクササイズ セッションを作成する

セッションを含む挿入リクエストの作成方法は以下のとおりです。

suspend fun writeExerciseSession(healthConnectClient: HealthConnectClient) {
    healthConnectClient.insertRecords(
        listOf(
            ExerciseSessionRecord(
                startTime = START_TIME,
                startZoneOffset = START_ZONE_OFFSET,
                endTime = END_TIME,
                endZoneOffset = END_ZONE_OFFSET,
                exerciseType = ExerciseSessionRecord.ExerciseType.RUNNING,
                title = "My Run",
                metadata = Metadata.manualEntry()
            ),
            // ... other records
        )
    )
}

エクササイズ セッションを読み取る

以下はエクササイズ セッションを読み取る方法の例です。

suspend fun readExerciseSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response =
        healthConnectClient.readRecords(
            ReadRecordsRequest(
                ExerciseSessionRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
    for (exerciseRecord in response.records) {
        // Process each exercise record
        // Optionally pull in with other data sources of the same time range.
        val distanceRecord =
            healthConnectClient
                .readRecords(
                    ReadRecordsRequest(
                        DistanceRecord::class,
                        timeRangeFilter =
                            TimeRangeFilter.between(
                                exerciseRecord.startTime,
                                exerciseRecord.endTime
                            )
                    )
                )
                .records
    }
}

サブタイプ データを作成する

セッションを必須ではないサブタイプ データで構成することもできます。このような追加情報により、セッションの内容を詳しく記録できます。

たとえば、エクササイズ セッションには ExerciseSegment クラス、ExerciseLap クラス、ExerciseRoute クラスを含められます。

val segments = listOf(
  ExerciseSegment(
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
    segmentType = ActivitySegmentType.BENCH_PRESS,
    repetitions = 373
  )
)

val laps = listOf(
  ExerciseLap(
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
    length = 0.meters
  )
)

ExerciseSessionRecord(
  exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_CALISTHENICS,
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
  startZoneOffset = ZoneOffset.UTC,
  endZoneOffset = ZoneOffset.UTC,
  segments = segments,
  laps = laps,
  route = route,
  metadata = Metadata.manualEntry()
)

エクササイズ セッションを削除する

エクササイズ セッションを削除する方法には次の 2 つがあります。

  1. 期間別
  2. UID 別

期間に応じてサブタイプ データを削除する方法は以下のとおりです。

suspend fun deleteExerciseSessionByTimeRange(
    healthConnectClient: HealthConnectClient,
    exerciseRecord: ExerciseSessionRecord,
) {
    val timeRangeFilter = TimeRangeFilter.between(exerciseRecord.startTime, exerciseRecord.endTime)
    healthConnectClient.deleteRecords(ExerciseSessionRecord::class, timeRangeFilter)
    // delete the associated distance record
    healthConnectClient.deleteRecords(DistanceRecord::class, timeRangeFilter)
}

UID ごとにサブタイプ データを削除することもできます。この操作で削除されるのはエクササイズ セッションのみで、関連データは削除されません。

suspend fun deleteExerciseSessionByUid(
    healthConnectClient: HealthConnectClient,
    exerciseRecord: ExerciseSessionRecord,
) {
    healthConnectClient.deleteRecords(
        ExerciseSessionRecord::class,
        recordIdsList = listOf(exerciseRecord.metadata.id),
        clientRecordIdsList = emptyList()
    )
}