Di chuyển Health Connect từ Android 13 (APK) sang Android 14 (khung)

Health Connect sẽ được đóng gói với Android 14 làm lớp lưu trữ dữ liệu chung cho dữ liệu sức khoẻ của người dùng, được bảo vệ bằng các quyền chi tiết và có thể truy cập được ở dạng ứng dụng hệ thống Android (gọi là mô-đun "khung" trong tài liệu này).

Nhà phát triển nên coi APK Health Connect (Android 13) là lớp khả năng tương thích ngược cho mô hình khung. Mô hình khung này sẽ giữ nguyên toàn bộ tính năng như phiên bản APK trước đó.

Trong quá trình chuyển đổi từ Android 13 sang Android 14, bạn phải đảm bảo trải nghiệm người dùng vừa mượt mà vừa trực quan nhất có thể.

Tài liệu này trình bày kế hoạch di chuyển, cung cấp một số ví dụ về trường hợp di chuyển và liệt kê các thay đổi đối với SDK Jetpack, nhằm tạo điều kiện để dễ dàng truy cập vào API Health Connect.

Kế hoạch di chuyển

  1. Sau khi phát hành Android 14, Google sẽ chuyển sang cung cấp Health Connect ở dạng ứng dụng hệ thống Android.
  2. Tiếp đó, hệ thống sẽ bổ sung dữ liệu cũ từ APK sau khi đạt được tính năng tương đương.
  3. Tất cả các điểm truy cập sẽ nhắm đến giao diện người dùng của ứng dụng hệ thống.
  4. Quá trình di chuyển dữ liệu sẽ bắt đầu. Khi quá trình di chuyển đang diễn ra, các API mô-đun sẽ bị tạm ngưng với trạng thái "Đang di chuyển". Trạng thái này cũng sẽ hiển thị trong giao diện người dùng Health Connect.
  5. Sau khi di chuyển xong, bạn có thể gỡ cài đặt APK.

Ví dụ về trường hợp di chuyển

Dưới đây là một số trường hợp mẫu giải thích về quá trình di chuyển cho cả hai loại dữ liệu interval và series:

Ví dụ 1 – Chạy (dữ liệu khoảng thời gian)

Một người dùng đã thu thập bản ghi dữ liệu chạy bộ trong 10 năm (1 giờ mỗi ngày). Dữ liệu này tương đương với:

  • Số bản ghi phiên tập thể dục: 365 * 10 * 1
  • Số bước: 365 * 10 * 1
  • Lượng calo: 365 * 10 * 1
  • Tổng = 365 * 10 * 3 (365 * 30) = 10.150

Vì 1 đoạn tương đương với 3.000 bản ghi nên tổng cộng dữ liệu ở trên rơi vào khoảng 4 đoạn.

Quá trình kiểm thử nội bộ của chúng tôi xác nhận rằng một đoạn thông thường mất khoảng một giây để chèn. Vì vậy, dữ liệu ở trên sẽ được di chuyển trong khoảng 4 giây.

Ví dụ 2 – Nhịp tim (dữ liệu về chuỗi nhịp tim)

Một người dùng đã thu thập dữ liệu nhịp tim trong 5 năm (một bản ghi được tạo mỗi phút), tổng cộng là 2.628.000 bản ghi.

Với 3.000 bản ghi mỗi đoạn, dữ liệu này sẽ được phân phối trên 876 đoạn. Vì 1 đoạn mất khoảng một giây để chèn nên dữ liệu này sẽ được di chuyển trong chưa đầy 15 phút.

Quy trình di chuyển đề xuất

Chúng tôi đã quyết định chọn chức năng di chuyển tức thì. Trong thực tế, việc này đồng nghĩa APK sẽ ngừng hoạt động ngay sau khi thiết bị được nâng cấp lên Android 14. Người dùng chỉ phải can thiệp ở mức tối thiểu.

Hãy cùng xem quy trình di chuyển cấp cao:

  1. Người dùng nâng cấp thiết bị lên Android 14.
  2. Jetpack 14 định tuyến người dùng đến các API mô-đun và chặn các API đó khi quá trình di chuyển đang diễn ra.
  3. Quá trình di chuyển bắt đầu khi phiên bản mô-đun có tính năng tương thích với APK – tức là phiên bản mô-đun chứa cùng một bộ tính năng hoặc nhiều hơn. Sau khi quá trình di chuyển bắt đầu, APK sẽ di chuyển các quyền và dữ liệu.
    1. Nếu cả hai phiên bản đều không có tính năng tương thích, thì bạn cần nâng cấp phiên bản mô-đun. Sau khi nâng cấp xong, quá trình di chuyển sẽ bắt đầu.
  4. Sau khi di chuyển xong, trạng thái sẽ đổi thành "Đã di chuyển xong" và các API mô-đun được bỏ chặn.
  5. Lúc này, bạn có thể gỡ cài đặt APK.

Phần tử trên giao diện người dùng trong quá trình di chuyển

Các màn hình sau đây do mô-đun khung hiển thị nhằm hướng dẫn người dùng, cả trước và trong quá trình di chuyển:

Hình 1. Nếu APK Health Connect không "nhận biết được quá trình di chuyển", hệ thống sẽ hiển thị lời nhắc hướng dẫn người dùng cập nhật APK. Nếu người dùng từ chối cập nhật, mô-đun này sẽ tiếp tục hoạt động và bắt đầu tích luỹ các quyền và dữ liệu:

Yêu cầu cập nhật số điện thoại


Hình 2. Nếu mô-đun khung này yêu cầu bản cập nhật để có tính năng tương thích, hệ thống sẽ hiển thị lời nhắc yêu cầu người dùng thực hiện quy trình cập nhật và khởi động lại thiết bị. Nếu người dùng từ chối cập nhật, mô-đun này sẽ tiếp tục hoạt động và bắt đầu tích luỹ các quyền và dữ liệu:

Yêu cầu cập nhật APK


Hình 3. Một vòng quay sẽ hiển thị trong quá trình di chuyển, cùng với nội dung giải thích rằng dữ liệu đang đồng bộ hoá:

Đang đồng bộ hoá dữ liệu

Dữ liệu được loại bỏ trùng lặp

Nếu mô-đun khung này đã bắt đầu thu nạp các dữ liệu và quyền trước khi thực hiện quá trình di chuyển hoặc khôi phục trên đám mây, thì các quy tắc sau sẽ áp dụng.

Quyền

Nếu đã có các quyền trong mô-đun khung này, thì mọi quyền trùng lặp được thu nạp từ APK sẽ bị bỏ qua trong quá trình di chuyển.

Dữ liệu

Trong quá trình di chuyển, dữ liệu trùng lặp từ APK sẽ bị bỏ qua. Hệ thống sẽ ưu tiên dữ liệu mới hơn từ mô-đun này.

Dữ liệu sẽ được loại bỏ trùng lặp trên clientRecordId nếu ứng dụng cung cấp mã nhận dạng bản ghi. Nếu không, khoảng thời gian (startTime và endTime cho bản ghi khoảng thời gian và time cho bản ghi tức thì) sẽ được coi là khoá, cùng với loại dữ liệu và tên gói của ứng dụng.

Các thay đổi trong SDK Jetpack

SDK Jetpack đóng vai trò là điểm tích hợp chung cho cả APK Health Connect và API khung Health Connect.

Nhà sản xuất thiết bị gốc (OEM) có thể bắt đầu tích hợp với Jetpack 13 để khi Jetpack 14 ra mắt, bạn có thể điều chỉnh thư viện mới và biên dịch thư viện đó trong Android 14.

Chúng tôi sẽ phát hành một phiên bản SDK mới hỗ trợ chuyển đổi sang Android 14. Bạn sẽ cần thực hiện một số thay đổi đối với nội dung tích hợp hiện có để đảm bảo quá trình chuyển đổi diễn ra suôn sẻ.

Khai báo quyền

Trong Android 13, bạn sẽ khai báo quyền bằng định dạng quyền tuỳ chỉnh trong một tệp tài nguyên được liên kết với tệp kê khai:

#AndroidManifest.xml

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
    <meta-data
        android:name="health_permissions"
        android:resource="@array/health_permissions"/>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

#health_permissions.xml

<resources>
  <array name="health_permissions">
    <item>androidx.health.permission.SleepSession.READ</item>
    <item>androidx.health.permission.SleepStage.READ</item>
    <item>androidx.health.permission.Weight.READ</item>
    <item>androidx.health.permission.Weight.WRITE</item>
  </array>
</resources>

Để hỗ trợ Android 14, nhà phát triển cần chuyển sang định dạng quyền tiêu chuẩn:

#AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP” />
<uses-permission android:name=”android.permission.health.READ_WEIGHT” />
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT” />

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata"/>
</queries>

Mở Health Connect

Hầu hết các ứng dụng bên thứ ba đều có nút mở ứng dụng Health Connect, chẳng hạn như nút "Quản lý quyền truy cập" trong Fitbit.

Trong Android 13, bạn có thể mở ứng dụng Health Connect bằng tên gói hoặc qua thao tác androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

Trong Android 14, bạn cần sử dụng thao tác theo ý định như chỉ định trong SDK Jetpack. Thao tác này có các giá trị khác nhau tuỳ theo phiên bản Android mà thao tác đó đang thực hiện:

@get:JvmName("getHealthConnectSettingsAction") @JvmStatic val ACTION_HEALTH_CONNECT_SETTINGS

Tải ứng dụng Health Connect

Chúng tôi đã tạo một API duy nhất tên là sdkStatus, có trong Jetpack 11, để thay thế 2 API khác không dùng nữa là IsSdkSupported() và isProviderAvailable().

Các thay đổi của API bản ghi phiên

4 loại phụ ExerciseSession đã bị xoá trong bản phát hành alpha10:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Giống như ExerciseSessionRecord, SleepStage sẽ trở thành loại phụ của SleepSession.

Cả hai loại phụ ExerciseSessionRecord và SleepSession sẽ được phát hành trong bản cập nhật SDK vào tháng 4.

Cập nhật loại phiên tập thể dục

Các loại phiên tập thể dục dưới đây sẽ không còn được hỗ trợ nữa, mà sau này sẽ được thêm vào dưới dạng loại phân đoạn:

  • EXERCISE_TYPE_BACK_EXTENSION
  • EXERCISE_TYPE_BARBELL_SHOULDER_PRESS
  • EXERCISE_TYPE_BENCH_PRESS
  • EXERCISE_TYPE_BENCH_SIT_UP
  • EXERCISE_TYPE_BURPEE
  • EXERCISE_TYPE_CRUNCH
  • EXERCISE_TYPE_DEADLIFT
  • EXERCISE_TYPE_DUMBBELL_CURL_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_CURL_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_FRONT_RAISE
  • EXERCISE_TYPE_DUMBBELL_LATERAL_RAISE
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_TWO_ARM
  • EXERCISE_TYPE_FORWARD_TWIST
  • EXERCISE_TYPE_JUMPING_JACK
  • EXERCISE_TYPE_JUMP_ROPE
  • EXERCISE_TYPE_LAT_PULL_DOWN
  • EXERCISE_TYPE_LUNGE
  • EXERCISE_TYPE_PLANK
  • EXERCISE_TYPE_SQUAT
  • EXERCISE_TYPE_UPPER_TWIST

Loại thay thế:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Xử lý nhật ký thay đổi

Nhật ký thay đổi sẽ không được di chuyển trong quá trình chuyển đổi từ APK sang Android 14.

Sau khi di chuyển xong, bạn sẽ bắt đầu nhận được ngoại lệ TOKEN_EXPIRED hoặc TOKEN_INVALID. Bạn nên xử lý các ngoại lệ này theo những cách sau (theo thứ tự ưu tiên):

1. Đọc và loại bỏ trùng lặp cho mọi dữ liệu kể từ dấu thời gian "lần đọc gần nhất" hoặc trong 30 ngày qua

Lưu trữ dấu thời gian về thời điểm một ứng dụng đọc dữ liệu lần gần đây nhất từ Health Connect. Khi mã thông báo hết hạn, dữ liệu phải được đọc lại từ giá trị này hoặc 30 ngày trước đó (bất kỳ giá trị nào tương đương với giá trị tối thiểu) và loại bỏ trùng lặp với dữ liệu đọc trước đây bằng mã nhận dạng duy nhất (UUID).

2. Đọc dữ liệu kể từ dấu thời gian "lần đọc gần nhất"

Thiết lập dấu thời gian cho biết thời điểm đọc dữ liệu gần đây nhất từ Health Connect. Khi hết hạn mã thông báo, hãy đọc tất cả dữ liệu sau giá trị đó.

3. Xoá và đọc lại dữ liệu trong 30 ngày qua

Xoá tất cả dữ liệu đã đọc từ Health Connect trong 30 ngày trước đó và đọc lại tất cả dữ liệu đó (ví dụ như khi các ứng dụng tích hợp với Health Connect lần đầu).

4. Không làm gì (tức là đọc lại dữ liệu trong 30 ngày qua và không loại bỏ dữ liệu trùng lặp)

Cách này nên được xem là phương án cuối cùng vì có nguy cơ hiển thị dữ liệu trùng lặp. Thay vào đó, nhà phát triển nên tìm hiểu các lựa chọn từ 1 đến 3 vì đã có mã nhận dạng duy nhất (UUID).

Kiểm thử API Android 14 bằng SDK Jetpack

SDK Jetpack Android 14 sẽ được phát hành vào ngày 7 tháng 6 năm 2023, cùng với bản phát hành Beta 3 của Android 14. Bạn sẽ cần bắt đầu biên dịch ứng dụng trên Android 14 để có thể sử dụng SDK Jetpack Android 14.

Nếu bạn muốn kiểm thử giải pháp của mình trên các Bản dùng thử cho nhà phát triển Android trước ngày 7 tháng 6, hãy liên hệ với đầu mối liên hệ của Google để được hỗ trợ.

Nếu muốn kiểm thử giải pháp trên bản phát hành Beta 3, bạn nên thực hiện các thay đổi sau trong APK của mình:

  1. Đặt compileSDKPreview = UpsideDownCake.
  2. Cập nhật tệp kê khai để thêm một ý định cho Android 14:
# AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP”/>
<uses-permission android:name=”android.permission.health.READ_WEIGHT”/>
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT”/>

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
</activity>

<activity-alias>
      android:name="AndroidURationaleActivity"
      android:exported="true"
      android:targetActivity=".RationaleActivity"
      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>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Tuỳ chỉnh nhà sản xuất thiết bị gốc (OEM)

Trong Android 14, các chế độ kiểm soát quy trình quản lý dữ liệu và quyền riêng tư của Health Connect sẽ nằm trong phần Cài đặt hệ thống.

Để giao diện của màn hình quyền và quản lý dữ liệu trông giống như một phần của thiết bị, Health Connect cung cấp tính năng sắp xếp theo chủ đề cho nhà sản xuất thiết bị gốc (OEM) thông qua việc sử dụng lớp phủ tuỳ chỉnh.

Để xem tài liệu về tính năng tạo kiểu cho nhà sản xuất thiết bị gốc (OEM), hãy tham khảo tài liệu về Các dịch vụ của Google dành cho thiết bị di động của Health Connect.