Làm quen với Health Connect

Hướng dẫn này tương thích với Health Connect phiên bản 1.1.0-alpha12.

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. Bạn có thể mở Health Connect thông qua phần Cài đặt, mặc dù đường dẫn có thể khác nhau tuỳ thuộc vào phiên bản Android:

  • Trên Android 14 trở lên: Chuyển đến phần Cài đặt > Bảo mật và quyền riêng tư > Chế độ kiểm soát quyền riêng tư > Health Connect hoặc tìm Health Connect trong phần Cài đặt.
  • Trên Android 13 trở xuống: 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.

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.2.0-alpha02"
  ...
}

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.

Kiểm tra phạm vi cung cấp của các tính năng

Khi các tính năng mới được thêm vào Health Connect, người dùng có thể không phải lúc nào cũng cập nhật phiên bản Health Connect của họ. Feature Availability API là một cách để kiểm tra xem một tính năng trong Health Connect có trên thiết bị của người dùng hay không và quyết định hành động cần thực hiện.

Hàm chính để kiểm tra phạm vi cung cấp của tính năng là getFeatureStatus(). Thao tác này trả về các hằng số nguyên FEATURE_STATUS_AVAILABLE hoặc FEATURE_STATUS_UNAVAILABLE:

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

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

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 kiểu dữ liệu bắt buộc đó. Các kiểu dữ liệu này phải khớp với những kiểu 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 Health Connect đã đượ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)
  }
}

Vì người dùng có thể cấp hoặc thu hồi quyền bất cứ lúc nào, nên ứ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.

Giúp người dùng làm quen

Nhiều ứng dụng có quy trình làm quen với ứng dụng tuỳ chỉnh, chẳng hạn như hướng dẫn về tính năng hoặc yêu cầu sự đồng ý của người dùng. Để cho phép Health Connect khởi chạy quy trình tham gia, hãy thêm nội dung sau vào tệp kê khai của bạn:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

Người dùng có thể bắt đầu kết nối với ứng dụng của bạn ngay từ ứng dụng Health Connect, thay vì từ bên trong ứng dụng của bạn. Nếu ứng dụng của bạn yêu cầu bất kỳ hoạt động tương tác bổ sung nào ngoài việc được cấp quyền đọc hoặc ghi dữ liệu, hãy cung cấp một hoạt động làm quen.

Lưu ý rằng người dùng có thể khởi chạy hoạt động làm quen với ứng dụng nhiều lần, chẳng hạn như nếu sau đó người dùng thu hồi các quyền đối với ứng dụng rồi kết nối lại.

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) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        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 readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each 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ẻ:

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.

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ư: