Làm quen với Health Connect

Hướng dẫn này chỉ cho bạn cách bắt đầu sử dụng Health Connect trên ứng dụng của mình.

Bước 1: Chuẩn bị ứng dụng Health Connect

Ứng dụng Health Connect chịu trách nhiệm xử lý tất cả các yêu cầu mà ứng dụng của bạn gửi qua SDK Health Connect. Các yêu cầu này bao gồm việc lưu trữ dữ liệu cũng như quản lý quyền đọc và ghi dữ liệu đó.

Quyền truy cập vào Health Connect phụ thuộc vào phiên bản Android được cài đặt trên điện thoại. Các phần sau đây trình bày cách xử lý một số phiên bản Android gần đây.

Android 14

Từ Android 14 (API cấp 34) trở đi, Health Connect là một phần của Khung Android. Phiên bản Health Connect này là một mô-đun khung. Do đó, bạn không cần thực hiện bước thiết lập.

Android 13 trở xuống

Trên các phiên bản Android 13 (API cấp 33) trở xuống, Health Connect không phải là một phần của Khung Android. Do đó, bạn cần cài đặt ứng dụng Health Connect trên Cửa hàng Google Play.

Nếu bạn đã tích hợp ứng dụng của mình với Health Connect trên Android 13 trở xuống và muốn di chuyển sang Android 14, hãy tham khảo bài viết Di chuyển từ Android 13 sang Android 14.

Mở ứng dụng Health Connect

Theo mặc định, Health Connect không còn xuất hiện trên Màn hình chính nữa. Để mở Health Connect, hãy chuyển đến phần Cài đặt > Ứng dụng > Health Connect hoặc thêm Health Connect vào trình đơn Cài đặt nhanh.

Ngoài ra, Health Connect yêu cầu người dùng phải bật phương thức khoá màn hình bằng mã PIN, hình mở khoá hoặc mật khẩu để dữ liệu sức khoẻ đang lưu trữ trong Health Connect được bảo vệ khỏi các bên độc hại khi thiết bị đang bị khoá. Để đặt một phương thức khoá màn hình, hãy chuyển đến phần Cài đặt > Bảo mật > Phương thức khoá màn hình.

Bước 2: Thêm SDK Health Connect vào ứng dụng của bạn

SDK Health Connect chịu trách nhiệm sử dụng API Health Connect để gửi các yêu cầu khi thực hiện những thao tác đối với kho dữ liệu trong ứng dụng Health Connect.

Thêm phần phụ thuộc SDK Health Connect vào tệp build.gradle ở cấp mô-đun:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alph10"
  ...
}

Bạn có thể tham khảo bản phát hành Health Connect để biết phiên bản mới nhất.

Bước 3: Định cấu hình ứng dụng

Các phần sau đây giải thích cách định cấu hình ứng dụng của bạn để tích hợp với Health Connect.

Khai báo quyền

Quyền truy cập vào dữ liệu về sức khoẻ và hoạt động thể dục là rất nhạy cảm. Health Connect triển khai một lớp bảo mật để đọc và ghi các thao tác, nhằm duy trì sự tin cậy của người dùng.

Trong ứng dụng, hãy khai báo quyền đọc và ghi trong tệp AndroidManifest.xml dựa trên các loại dữ liệu bắt buộc đó. Các loại dữ liệu này phải khớp với những loại dữ liệu mà bạn đã khai báo quyền truy cập trong Play Console.

Health Connect sử dụng định dạng khai báo quyền tiêu chuẩn của Android. Chỉ định các quyền bằng thẻ <uses-permission>. Hãy lồng các quyền này trong thẻ <manifest>.

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

Để biết danh sách đầy đủ các quyền và kiểu dữ liệu tương ứng, hãy xem Danh sách kiểu dữ liệu.

Hiện hộp thoại chính sách quyền riêng tư của ứng dụng

Tệp kê khai Android cần có một Hoạt động hiển thị chính sách quyền riêng tư của ứng dụng (lý do ứng dụng của bạn cần các quyền được yêu cầu), mô tả cách sử dụng và xử lý dữ liệu của người dùng.

Khai báo hoạt động này để xử lý ý định ACTION_SHOW_PERMISSIONS_RATIONALE. Ý định này được gửi đến ứng dụng khi người dùng nhấp vào đường liên kết chính sách quyền riêng tư trên màn hình hiện các quyền của Health Connect.

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

Tải một ứng dụng Health Connect

HealthConnectClient là điểm truy cập vào API Health Connect. Việc này cho phép ứng dụng dùng kho dữ liệu trong ứng dụng Health Connect, tự động quản lý quan hệ kết nối với lớp bộ nhớ cơ sở, đồng thời xử lý tất cả IPC cũng như quy trình chuyển đổi tuần tự các yêu cầu gửi đi và phản hồi gửi đến.

Để tải một phiên bản ứng dụng, trước tiên, hãy khai báo tên gói Health Connect trong tệp kê khai Android.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Sau đó, trong phần Hoạt động, hãy kiểm tra xem Health Connect đã được cài đặt hay chưa bằng cách sử dụng getSdkStatus. Nếu đã được cài đặt, hãy lấy một phiên bản HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // 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
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

Bước 4: Yêu cầu người dùng cấp quyền

Sau khi tạo một phiên bản ứng dụng, ứng dụng của bạn cần yêu cầu người dùng cấp quyền. Người dùng phải được phép cấp hoặc từ chối cấp quyền bất cứ lúc nào.

Để thực hiện việc này, hãy tạo một tập hợp quyền cho các kiểu dữ liệu bắt buộc. Trước tiên, bạn cần khai báo các quyền trong tập hợp này ở tệp kê khai Android.

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

Hãy sử dụng getGrantedPermissions để xem ứng dụng của bạn đã được cấp các quyền cần thiết chưa. Nếu chưa, hãy sử dụng createRequestPermissionResultContract để yêu cầu các quyền đó. Thao tác này sẽ hiện màn hình các quyền của 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)
  }
}

Đừng giả định rằng các quyền là không đổi vì người dùng có thể cấp hoặc thu hồi các quyền này bất cứ lúc nào. Ứng dụng của bạn cần kiểm tra định kỳ các quyền đã cấp và xử lý các tình huống khi mất quyền.

Bước 5: Thực hiện các thao tác

Giờ thì mọi thứ đã sẵn sàng, hãy thực hiện các thao tác đọc và ghi trong ứng dụng của bạn.

Ghi dữ liệu

Sắp xếp dữ liệu của bạn thành một bản ghi. Hãy xem danh sách các kiểu dữ liệu có trong Health Connect.

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

Sau đó, tạo bản ghi bằng hàm insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Đọc dữ liệu

Bạn có thể đọc từng dữ liệu bằng hàm readRecords.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    StepsRecord::class,
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        for (stepRecord in response.records) {
            // Process each step record
        }
    } catch (e: Exception) {
        // Run error handling here.
    }
}

Bạn cũng có thể đọc dữ liệu theo cách tổng hợp bằng hàm aggregate.

suspend fun aggregateSteps(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Video hướng dẫn

Hãy xem những video giải thích thêm về các tính năng của Health Connect, cũng như nguyên tắc về các phương pháp hay nhất để đảm bảo quá trình tích hợp diễn ra suôn sẻ:

• Managing permissions in Health Connect (Quản lý quyền trong Health Connect)
• Reading and writing in Health Connect (Đọc và ghi dữ liệu trong Health Connect)
• Mẹo tích hợp hiệu quả cho Health Connect

Tài nguyên

Hãy xem các tài nguyên sau đây để giúp cho quá trình phát triển sau này.

• SDK Health Connect (có trên Jetpack): Thêm SDK này vào ứng dụng của bạn để sử dụng API Health Connect.
• Tài liệu tham khảo API: Hãy xem Tài liệu tham khảo về Jetpack dành cho API Health Connect.
• Khai báo việc sử dụng các loại dữ liệu: Trong Play Console, hãy khai báo quyền truy cập vào các loại dữ liệu Health Connect mà ứng dụng của bạn đọc và ghi vào.
• Mã mẫu GitHub và lớp học lập trình (không bắt buộc): Hãy xem kho lưu trữ mã mẫu GitHub và bài tập trong lớp học lập trình để giúp bạn bắt đầu.

Các bước tiếp theo

Hãy xem Quy trình công việc phổ biến để tìm hiểu cách thực hiện các thao tác trong Health Connect, chẳng hạn như:

• Ghi dữ liệu
• Đọc dữ liệu thô
• Đọc dữ liệu tổng hợp