このページは Cloud Translation API によって翻訳されました。

トレーニング計画

このガイドは、Health Connect バージョン 1.1.0-alpha11 に対応しています。

ヘルスコネクトは、トレーニングアプリがトレーニングプランを書き込み、ワークアウトアプリがトレーニングプランを読み取れるように、予定されたエクササイズのデータ型を提供します。記録されたエクササイズ（ワークアウト）を読み戻して、ユーザーがトレーニング目標を達成できるように、パフォーマンスのパーソナライズされた分析を行うことができます。

機能の提供状況

ユーザーのデバイスがヘルスコネクトのトレーニングプランに対応しているかどうかを判断するには、クライアントで 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_PLANNED_EXERCISE
android.permission.health.WRITE_PLANNED_EXERCISE

予定されたエクササイズ機能をアプリに追加するには、まず、PlannedExerciseSession データ型に対する書き込み権限をリクエストします。

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

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

予定されているエクササイズを読み取るには、次の権限をリクエストする必要があります。

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

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

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

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

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(PlannedExerciseSessionRecord::class),
  HealthPermission.getWritePermission(PlannedExerciseSessionRecord::class),
  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)
  }
}

ユーザーはいつでも権限を付与または取り消すことができるため、アプリは許可されている権限を定期的に確認し、権限がなくなっている場合に対処できるようにする必要があります。

トレーニングプランはエクササイズセッションにリンクされます。そのため、ヘルスコネクトのこの機能を最大限に活用するには、トレーニングプランに関連する各レコードタイプを使用する権限をユーザーが与える必要があります。

たとえば、トレーニングプランで一連のランニング中のユーザーの心拍数を測定する場合、デベロッパーは、エクササイズセッションを書き込み、結果を読み取って後で評価するために、次の権限を宣言し、ユーザーに付与してもらう必要があるかもしれません。

android.permission.health.READ_EXERCISE
android.permission.health.READ_EXERCISE_ROUTES
android.permission.health.READ_HEART_RATE
android.permission.health.WRITE_EXERCISE
android.permission.health.WRITE_EXERCISE_ROUTE
android.permission.health.WRITE_HEART_RATE

ただし、トレーニングプランを作成してプランに対するパフォーマンスを評価するアプリは、トレーニングプランを使用して実際のエクササイズデータを書き込むアプリとは異なることがよくあります。アプリの種類によっては、すべての読み取り / 書き込み権限が必要になるわけではありません。たとえば、アプリの種類ごとに次の権限のみが必要になる場合があります。

トレーニング計画アプリ	ワークアウトアプリ
`WRITE_PLANNED_EXERCISE`	`READ_PLANNED_EXERCISE`
`READ_EXERCISE`	`WRITE_EXERCISE`
`READ_EXERCISE_ROUTES`	`WRITE_EXERCISE_ROUTE`
`READ_HEART_RATE`	`WRITE_HEART_RATE`

予定されたエクササイズセッションの記録に含まれる情報

セッションのタイトル。
予定されているエクササイズブロックのリスト。
セッションの開始時間と終了時間。
エクササイズの種類。
アクティビティのメモ。
メタデータ。
完了したエクササイズセッション ID - この予定されたエクササイズセッションに関連するエクササイズセッションが完了すると、自動的に書き込まれます。

予定されたエクササイズブロックの記録に含まれる情報

予定されたエクササイズブロックには、エクササイズステップのリストが含まれています。これは、さまざまなステップのグループの繰り返しをサポートするためです（たとえば、アームカール、バーピー、クランチのシーケンスを 5 回連続で行うなど）。

ブロックの説明。
予定されているエクササイズステップのリスト。
繰り返し回数。

予定されたエクササイズステップの記録に含まれる情報

サポートされている集計

このデータ型でサポートされている集計はありません。

使用例

たとえば、ユーザーが 2 日後に 90 分間のランニングを予定しているとします。このランニングでは、湖の周りを 3 周し、目標心拍数を 90 ～ 110 bpm に設定します。

次の内容の予定されたエクササイズセッションは、トレーニングプランアプリでユーザーによって定義されます。
1. ランニングの予定開始時刻と終了時刻
2. エクササイズのタイプ（ランニング）
3. 周回数（反復回数）
4. 心拍数のパフォーマンス目標（90 ～ 110 bpm）
この情報は、エクササイズブロックと歩数にグループ化され、トレーニングプランアプリによって PlannedExerciseSessionRecord としてヘルスコネクトに書き込まれます。
ユーザーが予定されたセッション（ランニング）を実行します。
セッションに関連するエクササイズデータは、次のいずれかの方法で記録されます。
1. セッション中にウェアラブルデバイスで測定された場合。たとえば、心拍数などです。このデータは、アクティビティのレコードタイプとしてヘルスコネクトに書き込まれます。この場合は HeartRateRecord です。
2. セッション後にユーザーが手動で設定する。たとえば、実際の実行の開始と終了を示す場合などです。このデータは ExerciseSessionRecord としてヘルスコネクトに書き込まれます。
後で、トレーニングプランアプリはヘルスコネクトからデータを読み取り、計画されたエクササイズセッションでユーザーが設定した目標に対する実際のパフォーマンスを評価します。

エクササイズを計画して目標を設定する

ユーザーは、将来のエクササイズを計画して目標を設定できます。これを予定されているエクササイズセッションとしてヘルスコネクトに書き込みます。

使用例で説明した例では、ユーザーは 2 日後の 90 分間のランニングを計画しています。このランニングでは、湖の周りを 3 周し、目標心拍数を 90 ～ 110 bpm に設定します。

このようなスニペットは、予定されているエクササイズセッションをヘルスコネクトに記録するアプリのフォームハンドラで見つかることがあります。また、トレーニングを提供するサービスなど、インテグレーションの取り込みポイントで確認することもできます。

// Verify the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
      HealthPermission.getWritePermission(PlannedExerciseSessionRecord::class))) {
    // The user hasn't granted the app permission to write planned exercise session data.
    return
}

val plannedDuration = Duration.ofMinutes(90)
val plannedStartDate = LocalDate.now().plusDays(2)

val plannedExerciseSessionRecord = PlannedExerciseSessionRecord(
    startDate = plannedStartDate,
    duration = plannedDuration,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    blocks = listOf(
        PlannedExerciseBlock(
            repetitions = 1, steps = listOf(
                PlannedExerciseStep(
                    exerciseType = ExerciseSegment.EXERCISE_SEGMENT_TYPE_RUNNING,
                    exercisePhase = PlannedExerciseStep.EXERCISE_PHASE_ACTIVE,
                    completionGoal = ExerciseCompletionGoal.RepetitionsGoal(repetitions = 3),
                    performanceTargets = listOf(
                        ExercisePerformanceTarget.HeartRateTarget(
                            minHeartRate = 90.0, maxHeartRate = 110.0
                        )
                    )
                ),
            ), description = "Three laps around the lake"
        )
    ),
    title = "Run at lake",
    notes = null,
    metadata = Metadata.manualEntry(
      device = Device(type = Device.Companion.TYPE_PHONE)
    )
)
val insertedPlannedExerciseSessions =
    healthConnectClient.insertRecords(listOf(plannedExerciseSessionRecord)).recordIdsList
val insertedPlannedExerciseSessionId = insertedPlannedExerciseSessions.first()

エクササイズとアクティビティのデータを記録する

2 日後、ユーザーが実際のエクササイズセッションを記録します。これをヘルスコネクトにエクササイズセッションとして書き込みます。

この例では、ユーザーのセッション継続時間が予定の継続時間と完全に一致しています。

次のスニペットは、エクササイズセッションをヘルスコネクトに記録するアプリのフォームハンドラで見つかる可能性があります。また、エクササイズセッションを検出してログに記録できるウェアラブルのデータ取り込みハンドラとデータエクスポートハンドラにも含まれている可能性があります。

ここで insertedPlannedExerciseSessionId は、前の例から再利用されています。実際のアプリでは、既存のセッションのリストから予定されているエクササイズセッションをユーザーが選択することで、ID が決定されます。

// Verify the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
      HealthPermission.getWritePermission(ExerciseSessionRecord::class))) {
    // The user doesn't granted the app permission to write exercise session data.
    return
}

val sessionDuration = Duration.ofMinutes(90)
val sessionEndTime = Instant.now()
val sessionStartTime = sessionEndTime.minus(sessionDuration)

val exerciseSessionRecord = ExerciseSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    segments = listOf(
        ExerciseSegment(
            startTime = sessionStartTime,
            endTime = sessionEndTime,
            repetitions = 3,
            segmentType = ExerciseSegment.EXERCISE_SEGMENT_TYPE_RUNNING
        )
    ),
    title = "Run at lake",
    plannedExerciseSessionId = insertedPlannedExerciseSessionId,
    metadata = Metadata.manualEntry(
      device = Device(type = Device.Companion.TYPE_PHONE)
    )
)
val insertedExerciseSessions =
    healthConnectClient.insertRecords(listOf(exerciseSessionRecord))

ウェアラブルデバイスは、ランニング中の心拍数も記録します。次のスニペットを使用して、ターゲット範囲内のレコードを生成できます。

実際のアプリでは、このスニペットの主要部分はウェアラブルからのメッセージのハンドラにあり、収集時に測定値をヘルスコネクトに書き込みます。

// Verify the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
      HealthPermission.getWritePermission(HeartRateRecord::class))) {
    // The user doesn't granted the app permission to write heart rate record data.
    return
}

val samples = mutableListOf<HeartRateRecord.Sample>()
var currentTime = sessionStartTime
while (currentTime.isBefore(sessionEndTime)) {
    val bpm = Random.nextInt(21) + 90
    val heartRateRecord = HeartRateRecord.Sample(
        time = currentTime,
        beatsPerMinute = bpm.toLong(),
    )
    samples.add(heartRateRecord)
    currentTime = currentTime.plusSeconds(180)
}

val heartRateRecord = HeartRateRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    samples = samples,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.Companion.TYPE_WATCH)
    )
)
val insertedHeartRateRecords = healthConnectClient.insertRecords(listOf(heartRateRecord))

パフォーマンス目標を評価する

ユーザーのワークアウトの翌日、記録されたエクササイズを取得し、計画されたエクササイズ目標を確認し、追加のデータ型を評価して、設定された目標が達成されたかどうかを判断できます。

このようなスニペットは、パフォーマンス目標を評価する定期的なジョブや、エクササイズのリストを読み込んでアプリでパフォーマンス目標に関する通知を表示する際に使用される可能性があります。

// Verify the user has granted all necessary permissions for this task
val grantedPermissions =
     healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.containsAll(
        listOf(
            HealthPermission.getReadPermission(ExerciseSessionRecord::class),
            HealthPermission.getReadPermission(PlannedExerciseSessionRecord::class),
            HealthPermission.getReadPermission(HeartRateRecord::class)
        )
    )
) {
    // The user doesn't granted the app permission to read exercise session record data.
    return
}

val searchDuration = Duration.ofDays(1)
val searchEndTime = Instant.now()
val searchStartTime = searchEndTime.minus(searchDuration)

val response = healthConnectClient.readRecords(
    ReadRecordsRequest<ExerciseSessionRecord>(
        timeRangeFilter = TimeRangeFilter.between(searchStartTime, searchEndTime)
    )
)
for (exerciseRecord in response.records) {
    val plannedExerciseRecordId = exerciseRecord.plannedExerciseSessionId
    val plannedExerciseRecord =
        if (plannedExerciseRecordId == null) null else healthConnectClient.readRecord(
            PlannedExerciseSessionRecord::class, plannedExerciseRecordId
        ).record
    if (plannedExerciseRecord != null) {
        val aggregateRequest = AggregateRequest(
            metrics = setOf(HeartRateRecord.BPM_AVG),
            timeRangeFilter = TimeRangeFilter.between(
                exerciseRecord.startTime, exerciseRecord.endTime
            ),
        )
        val aggregationResult = healthConnectClient.aggregate(aggregateRequest)

        val maxBpm = aggregationResult[HeartRateRecord.BPM_MAX]
        val minBpm = aggregationResult[HeartRateRecord.BPM_MIN]
        if (maxBpm != null && minBpm != null) {
            plannedExerciseRecord.blocks.forEach { block ->
                block.steps.forEach { step ->
                    step.performanceTargets.forEach { target ->
                        when (target) {
                            is ExercisePerformanceTarget.HeartRateTarget -> {
                                val minTarget = target.minHeartRate
                                val maxTarget = target.maxHeartRate
                                if(
                                    minBpm >= minTarget && maxBpm <= maxTarget
                                ) {
                                  // Success!
                                }
                            }
                            // Handle more target types
                            }
                        }
                    }
                }
            }
        }
    }
}

エクササイズセッション

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

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

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

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"
            ),
            // ... 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
)

トレーニング計画 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

機能の提供状況

必要な権限

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

関連する権限

予定されたエクササイズ セッションの記録に含まれる情報

予定されたエクササイズ ブロックの記録に含まれる情報

予定されたエクササイズ ステップの記録に含まれる情報