このガイドは、Health Connect バージョン 1.1.0-alpha12 に対応しています。
エクササイズのルートを使用すると、関連するエクササイズ アクティビティの GPS ルートを追跡し、ワークアウトのマップを他のアプリと共有できます。
このガイドでは、ユーザーに権限をリクエストする方法と、エクササイズ セッションの一部としてルートデータを書き込む権限をアプリがどのように取得するかについて説明します。
エクササイズのルートの読み取り / 書き込み機能の概要は次のとおりです。
- アプリは、エクササイズのルート用の新しい書き込み権限を作成します。
- 挿入は、ルートをフィールドとしてエクササイズのセッションを書き込むことで行われます。
- 読み取り:
- セッション オーナーの場合、セッション読み取りを使用してデータにアクセスします。
- サードパーティ アプリで、ユーザーがルートの 1 回限りの読み取りを許可できるダイアログを表示します。
ユーザーに権限をリクエストする
クライアント インスタンスを作成した後、アプリはユーザーに権限をリクエストする必要があります。ユーザーがいつでも権限を付与または拒否できるようにする必要があります。
そのためには、必要なデータ型の権限セットを作成します。まず、セット内の権限が 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)
}
}
ユーザーはいつでも権限を付与または取り消すことができるため、アプリは許可されている権限を定期的に確認し、権限が失われた場合に対処する必要があります。
エクササイズ ルートの書き込み権限と読み取り権限
エクササイズのルートには、独自のランタイム書き込み権限(android.permission.health.WRITE_EXERCISE_ROUTE
)があります。
エクササイズのルート機能をアプリに追加するには、まず、特定のデータ型に対する書き込み権限をリクエストします。
また、各ルートはエクササイズ セッションに関連付けられているため、エクササイズ権限を宣言する必要があります(1 セッション = 1 ワークアウト)。
エクササイズのルートを記述するために宣言する必要がある権限は次のとおりです。
<application>
<uses-permission
android:name="android.permission.health.WRITE_EXERCISE_ROUTE" />
<uses-permission
android:name="android.permission.health.WRITE_EXERCISE" />
...
</application>
エクササイズのルートを読み取るには、次の権限をリクエストする必要があります。
<application>
<uses-permission
android:name="android.permission.health.READ_EXERCISE_ROUTES" />
<uses-permission
android:name="android.permission.health.READ_EXERCISE" />
...
</application>
権限をリクエストするには、最初にアプリをヘルスコネクトに接続するときに PermissionController.createRequestPermissionResultContract()
メソッドを使用します。必要に応じてリクエストする権限は次のとおりです。
- 健康に関するデータ(ルートデータを含む)の読み取り:
HealthPermission.getReadPermission(ExerciseSessionRecord::class)
- 健康に関するデータ(ルートデータを含む)の書き込み:
HealthPermission.getWritePermission(ExerciseSessionRecord::class)
- エクササイズのルートデータの書き込み:
HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE
ルートデータの読み取りと書き込み
アプリは、ルートをフィールドとして持つセッションを書き込むことで、ルートを挿入します。
ユーザーに書き込み権限がなく、ルートが設定されていない場合、ルートは更新されません。
アプリにルート書き込み権限があり、ルートのないセッション オブジェクトを渡してセッションを更新しようとすると、既存のルートが削除されます。
アプリがサードパーティ アプリから提供されたルートデータを読み取る必要があるたびに、読み取りオペレーションを許可するようにユーザーに求めるダイアログが表示されます。
セッションからルートをリクエストする
ヘルスコネクトでセッションを読み取り、そのセッションからルートをリクエストする方法は次のとおりです。
suspend fun readExerciseSessionAndRoute() {
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofHours(1))
val grantedPermissions =
healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
HealthPermission.getReadPermission(ExerciseSessionRecord::class))) {
// The user doesn't allow the app to read exercise session data.
return
}
val readResponse =
healthConnectClient.readRecords(
ReadRecordsRequest(
ExerciseSessionRecord::class,
TimeRangeFilter.between(startTime, endTime)
)
)
val exerciseRecord = readResponse.records.first()
val recordId = exerciseRecord.metadata.id
// See https://developer.android.com/training/basics/intents/result#launch
// for appropriately handling ActivityResultContract.
val requestExerciseRouteLauncher = fragment.registerForActivityResul
(ExerciseRouteRequestContract()) { exerciseRoute: ExerciseRoute? ->
if (exerciseRoute != null) {
displayExerciseRoute(exerciseRoute)
} else {
// Consent was denied
}
}
val exerciseSessionRecord =
healthConnectClient.readRecord(ExerciseSessionRecord::class, recordId).record
when (val exerciseRouteResult = exerciseSessionRecord.exerciseRouteResult) {
is ExerciseRouteResult.Data ->
displayExerciseRoute(exerciseRouteResult.exerciseRoute)
is ExerciseRouteResult.ConsentRequired ->
requestExerciseRouteLauncher.launch(recordId)
is ExerciseRouteResult.NoData -> Unit // No exercise route to show
else -> Unit
}
}
fun displayExerciseRoute(route: ExerciseRoute?) {
val locations = route.route.orEmpty()
for (location in locations) {
// Handle location.
}
}
セッションからルートを書き込む
次のコードはエクササイズのルートを含むセッションを記録する方法を示しています。
suspend fun InsertExerciseRoute(healthConnectClient: HealthConnectClient) {
val grantedPermissions =
healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
getWritePermission(ExerciseSessionRecord::class))) {
// The user doesn't allow the app to write exercise session data.
return
}
val sessionStartTime = Instant.now()
val sessionDuration = Duration.ofMinutes(20)
val sessionEndTime = sessionStartTime.plus(sessionDuration)
val exerciseRoute =
if (grantedPermissions.contains(PERMISSION_WRITE_EXERCISE_ROUTE)) ExerciseRoute(
listOf(
ExerciseRoute.Location(
// Location times must be on or after the session start time
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(
// Location times must be before the session end time
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
// The user doesn't allow the app to write exercise route data.
null
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.manualEntry(
device = Device(type = Device.TYPE_PHONE)
),
)
val response = healthConnectClient.insertRecords(listOf(exerciseSessionRecord))
}