เพิ่มเส้นทางออกกำลังกาย

คู่มือนี้ใช้ได้กับ Health Connect เวอร์ชัน 1.1.0-alpha12

เส้นทางการออกกำลังกายช่วยให้ผู้ใช้ติดตามเส้นทาง GPS สำหรับกิจกรรมการออกกำลังกายที่เกี่ยวข้อง และแชร์แผนที่การออกกำลังกายกับแอปอื่นๆ ได้

ความพร้อมใช้งานของฟีเจอร์

หากต้องการดูว่าอุปกรณ์ของผู้ใช้รองรับเส้นทางออกกำลังกายใน Health Connect หรือไม่ ให้ตรวจสอบความพร้อมใช้งานของ FEATURE_PLANNED_EXERCISE ในไคลเอ็นต์ ดังนี้

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

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

ดูข้อมูลเพิ่มเติมได้ที่ตรวจสอบความพร้อมใช้งานของฟีเจอร์

คู่มือนี้ให้ข้อมูลเกี่ยวกับวิธีขอสิทธิ์จากผู้ใช้ และยังอธิบายวิธีที่แอปได้รับสิทธิ์ในการเขียนข้อมูลเส้นทางเป็นส่วนหนึ่งของเซสชันการออกกำลังกายด้วย

ฟังก์ชันการอ่านและการเขียนสำหรับเส้นทางการออกกำลังกายมีดังนี้

  1. แอปสร้างสิทธิ์เขียนใหม่สำหรับเส้นทางการออกกำลังกาย
  2. การแทรกจะเกิดขึ้นโดยการเขียนเซสชันการออกกำลังกายที่มีเส้นทางเป็นฟิลด์
  3. การอ่าน
    1. สำหรับเจ้าของเซสชัน ระบบจะเข้าถึงข้อมูลโดยใช้การอ่านเซสชัน
    2. จากแอปของบุคคลที่สามผ่านกล่องโต้ตอบที่อนุญาตให้ผู้ใช้ให้สิทธิ์ อ่านเส้นทางแบบครั้งเดียว

หากผู้ใช้ไม่มีสิทธิ์เขียนและไม่ได้ตั้งค่าเส้นทาง เส้นทางจะไม่ได้รับการอัปเดต

หากแอปมีสิทธิ์เขียนเส้นทางและพยายามอัปเดตเซสชันโดย ส่งออบเจ็กต์เซสชันที่ไม่มีเส้นทาง ระบบจะลบเส้นทางที่มีอยู่

สิทธิ์ที่จำเป็น

การเข้าถึงเส้นทางการออกกำลังกายได้รับการคุ้มครองโดยสิทธิ์ต่อไปนี้

  • android.permission.health.READ_EXERCISE_ROUTE
  • android.permission.health.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_ROUTE" />
...
</application>

นอกจากนี้ คุณยังต้องประกาศสิทธิ์การออกกำลังกายด้วย เนื่องจากแต่ละเส้นทางจะเชื่อมโยงกับเซสชันการออกกำลังกาย (1 เซสชัน = 1 การออกกำลังกาย)

หากต้องการขอสิทธิ์ ให้ใช้วิธี PermissionController.createRequestPermissionResultContract() เมื่อคุณ เชื่อมต่อแอปกับ Health Connect เป็นครั้งแรก สิทธิ์บางอย่างที่คุณอาจ ต้องการขอมีดังนี้

  • อ่านข้อมูลสุขภาพ รวมถึงข้อมูลเส้นทาง HealthPermission.getReadPermission(ExerciseSessionRecord::class)
  • เขียนข้อมูลสุขภาพ รวมถึงข้อมูลเส้นทาง: HealthPermission.getWritePermission(ExerciseSessionRecord::class)
  • เขียนข้อมูลเส้นทางออกกำลังกาย: HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

ขอสิทธิ์จากผู้ใช้

หลังจากสร้างอินสแตนซ์ไคลเอ็นต์แล้ว แอปของคุณต้องขอสิทธิ์จากผู้ใช้ ผู้ใช้ต้องได้รับอนุญาตให้ให้หรือปฏิเสธสิทธิ์ได้ทุกเมื่อ

โดยให้สร้างชุดสิทธิ์สำหรับประเภทข้อมูลที่จำเป็น ตรวจสอบว่าได้ประกาศสิทธิ์ในชุดไว้ใน Android manifest ก่อน

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

ใช้ getGrantedPermissions เพื่อดูว่าแอปของคุณได้รับสิทธิ์ที่จำเป็นแล้วหรือไม่ หากไม่มี ให้ใช้ createRequestPermissionResultContract เพื่อขอสิทธิ์เหล่านั้น ซึ่งจะแสดงหน้าจอสิทธิ์ของ Health Connect

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

เนื่องจากผู้ใช้สามารถให้หรือเพิกถอนสิทธิ์ได้ทุกเมื่อ แอปของคุณจึงต้อง ตรวจสอบสิทธิ์ที่ได้รับเป็นระยะๆ และจัดการสถานการณ์ที่ สิทธิ์สูญหาย

ข้อมูลที่รวมอยู่ในบันทึกเซสชันการออกกำลังกาย

บันทึกเซสชันการออกกำลังกายแต่ละรายการจะมีข้อมูลต่อไปนี้

  • ประเภทการออกกำลังกาย เช่น การปั่นจักรยาน
  • เส้นทางการออกกำลังกาย ซึ่งมีข้อมูลต่างๆ เช่น ละติจูด ลองจิจูด และระดับความสูง

การรวมที่รองรับ

ไม่มีการรวบรวมที่รองรับสำหรับข้อมูลประเภทนี้

ตัวอย่างการใช้งาน

ขอเส้นทางหรือเขียนเส้นทางจากเซสชัน

ขอเส้นทางจากเซสชัน

วิธีอ่านเซสชันใน Health Connect และขอเส้นทางจากเซสชันนั้นมีดังนี้

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