Hướng dẫn này tương thích với Health Connect phiên bản 1.2.0-alpha05 trở lên.
Có một số thay đổi đối với siêu dữ liệu trong Health Connect dành cho nhà phát triển nâng cấp lên bản phát hành 1.1.0-alpha12 trở lên.
Thông tin về thư viện
Mã cấu phần phần mềm Trình bổ trợ Android cho Gradle của Google Maven xác định thư viện Health Connect mà bạn cần nâng cấp.
Thêm phần phụ thuộc SDK Health Connect này vào tệp build.gradle ở cấp mô-đun:
dependencies {
implementation "androidx.health.connect:connect-client:1.1.0-alpha12"
}
Thay đổi siêu dữ liệu
Hai thay đổi về siêu dữ liệu đã được đưa vào SDK Health Connect trên Jetpack kể từ phiên bản 1.1.0-alpha12 để giúp xác minh rằng siêu dữ liệu hữu ích bổ sung có tồn tại trong hệ sinh thái. Nếu metadata không có trong hàm khởi tạo Record, bạn có thể thấy lỗi Constructor internal (Hàm khởi tạo nội bộ).
Chỉ định phương thức ghi
Bạn phải chỉ định thông tin chi tiết về siêu dữ liệu bất cứ khi nào
một đối tượng thuộc loại Record() được tạo thực thể.
Khi ghi dữ liệu vào Health Connect, bạn phải chỉ định một trong bốn phương thức ghi bằng cách sử dụng một trong các phương thức ban đầu tương ứng để tạo thực thể Metadata:
| Phương thức ghi | Mô tả |
|---|---|
RECORDING_METHOD_UNKNOWN |
Không thể xác minh phương thức ghi âm. |
RECORDING_METHOD_MANUAL_ENTRY |
Người dùng đã nhập dữ liệu. |
RECORDING_METHOD_AUTOMATICALLY_RECORDED |
Một thiết bị hoặc cảm biến đã ghi lại dữ liệu. |
RECORDING_METHOD_ACTIVELY_RECORDED |
Người dùng đã bắt đầu hoặc kết thúc phiên ghi trên một thiết bị. |
Ví dụ:
StepsRecord( startTime = Instant.ofEpochMilli(1234L), startZoneOffset = null, endTime = Instant.ofEpochMilli(1236L), endZoneOffset = null, metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH)), count = 10 )
Loại thiết bị
Bạn phải chỉ định loại thiết bị cho tất cả
dữ liệu được ghi lại tự động và chủ động. Để biết thêm thông tin, hãy xem
lớp Device trong tài liệu về Jetpack. Các loại thiết bị hiện tại bao gồm:
| Loại thiết bị | Mô tả |
|---|---|
TYPE_UNKNOWN |
Không xác định được loại thiết bị. |
TYPE_WATCH |
Loại thiết bị là đồng hồ. |
TYPE_PHONE |
Loại thiết bị là điện thoại. |
TYPE_SCALE |
Loại thiết bị là cân. |
TYPE_RING |
Loại thiết bị là nhẫn. |
TYPE_HEAD_MOUNTED |
Loại thiết bị là thiết bị đeo trên đầu. |
TYPE_FITNESS_BAND |
Loại thiết bị là vòng đeo tay thể dục. |
TYPE_CHEST_STRAP |
Loại thiết bị là dây đeo ngực. |
TYPE_SMART_DISPLAY |
Loại thiết bị là màn hình thông minh. |
Một số giá trị Device.type chỉ có trên các phiên bản Health Connect mới hơn. Khi tính năng loại thiết bị mở rộng không hoạt động, các loại này sẽ được coi là Device.TYPE_UNKNOWN.
| Loại thiết bị mở rộng | Mô tả |
|---|---|
TYPE_CONSUMER_MEDICAL_DEVICE |
Loại thiết bị là thiết bị y tế. |
TYPE_GLASSES |
Loại thiết bị là kính thông minh hoặc kính mắt. |
TYPE_HEARABLE |
Loại thiết bị là thiết bị nghe. |
TYPE_FITNESS_MACHINE |
Loại thiết bị là máy cố định. |
TYPE_FITNESS_EQUIPMENT |
Loại thiết bị là thiết bị tập thể dục. |
TYPE_PORTABLE_COMPUTER |
Loại thiết bị là máy tính xách tay. |
TYPE_METER |
Loại thiết bị là đồng hồ đo. |
FEATURE_EXTENDED_DEVICE_TYPES có hoạt động trên ứng dụng khách hay không:
if (healthConnectClient
.features
.getFeatureStatus(
HealthConnectFeatures.FEATURE_EXTENDED_DEVICE_TYPES
) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {
// Feature is available
} else {
// Feature isn't available
}
Ví dụ:
val WATCH_DEVICE = Device( manufacturer = "Google", model = "Pixel Watch", type = Device.TYPE_WATCH ) // Phone val PHONE_DEVICE = Device( manufacturer = "Google", model = "Pixel 8", type = Device.TYPE_PHONE ) // Ring val RING_DEVICE = Device( manufacturer = "Oura", model = "Ring Gen3", type = Device.TYPE_RING ) // Scale val SCALE_DEVICE = Device( manufacturer = "Withings", model = "Body Comp", type = Device.TYPE_SCALE )
Mã nhận dạng thiết bị duy nhất (UDI)
Đối với Health Connect trên Android 17 (cấp độ API 37.1) hoặc
U extension 23 trở lên, lớp Device hỗ trợ giá trị nhận dạng thiết bị duy nhất (UDI). Việc liên kết thông tin chi tiết về mẫu UDI đã đăng ký của thiết bị y tế với hồ sơ bằng văn bản của bạn cho phép các ứng dụng hạ nguồn (chẳng hạn như nền tảng chăm sóc sức khoẻ từ xa hoặc cổng thông tin lâm sàng) xác định các chỉ số lâm sàng và phân biệt các chỉ số đó với dữ liệu chung về thiết bị đeo của người tiêu dùng.
Khai báo quyền .
Để ghi thông tin chi tiết về UDI vào Health Connect, bạn phải khai báo quyền WRITE_DEVICE_UDI trong tệp AndroidManifest.xml của ứng dụng:
<uses-permission android:name="android.permission.health.WRITE_DEVICE_UDI" />
Xin lưu ý rằng WRITE_DEVICE_UDI là một quyền thông thường. Bạn phải khai báo quyền này trong tệp kê khai, nhưng không cần yêu cầu người dùng cấp quyền trong thời gian chạy. Quyền này tự động được cấp cho ứng dụng của bạn tại thời điểm cài đặt.
Chỉ viết phần Giá trị nhận dạng thiết bị (DI)
Một UDI hoàn chỉnh gồm hai phần:
- Mã nhận dạng thiết bị (UDI-DI): Mã nhận dạng được công nhận trên toàn cầu do một cơ quan cấp (ví dụ: GS1) chỉ định cho một mẫu thiết bị cụ thể.
- Mã nhận dạng sản phẩm (UDI-PI): Các thuộc tính dành riêng cho đơn vị, chẳng hạn như số sê-ri, số lô, ngày sản xuất hoặc ngày hết hạn.
Để bảo vệ quyền riêng tư của người dùng, chỉ điền phần UDI-DI của mã trong Health Connect. Đừng thêm bất kỳ thuộc tính mã nhận dạng sản phẩm nào (chẳng hạn như số sê-ri hoặc số lô).
Ví dụ về mã
Lưu ý: Bạn có thể đặt UDI khi tạo một thực thể Device.
SDK Jetpack
val device = Device( type = Device.TYPE_CONSUMER_MEDICAL_DEVICE, manufacturer = "Omron", model = "HEM-7121", udi = "04015674011832" // Device Identifier (UDI-DI) portion only )
API nền tảng
val device = Device.Builder() .setType(Device.DEVICE_TYPE_CONSUMER_MEDICAL_DEVICE) .setManufacturer("Omron") .setModel("HEM-7121") .setUdi("04015674011832") // Device Identifier (UDI-DI) portion only .build()
Nếu bạn ghi dữ liệu có UDI mà không khai báo quyền WRITE_DEVICE_UDI, Health Connect sẽ gửi SecurityException tại thời điểm ghi.
Sử dụng UDI để xác minh giấy phép của thiết bị
Health Connect đóng vai trò là một tầng truyền tải và không xác thực tính xác thực hoặc trạng thái đăng ký của UDI.
Đối với trình đọc dữ liệu, sự hiện diện của UDI cho biết dữ liệu bắt nguồn từ một thiết bị y tế đã đăng ký. Ứng dụng đọc nên truy vấn các cơ sở dữ liệu theo quy định như Cơ sở dữ liệu nhận dạng thiết bị duy nhất trên toàn cầu (GUDID) của FDA hoặc EUDAMED của Liên minh Châu Âu để xác minh thông tin phân loại thiết bị, trạng thái phê duyệt theo quy định (ví dụ: Loại I, II hoặc III) hoặc mục đích sử dụng cụ thể.
Đã cập nhật đoạn trích
Hướng dẫn về Health Connect đã được cập nhật ở những nơi cần có đoạn mã mới để tuân thủ các yêu cầu mới về siêu dữ liệu. Để xem một số ví dụ, hãy tham khảo trang Ghi dữ liệu.
Các phương thức siêu dữ liệu mới
Bạn không thể trực tiếp tạo thực thể cho siêu dữ liệu nữa, vì vậy, hãy sử dụng một trong các phương thức nhà máy để lấy một thực thể siêu dữ liệu mới. Các phương thức nhà máy xác minh rằng thông tin thiết bị được cung cấp khi thiết bị hoặc cảm biến được dùng để ghi lại dữ liệu. Đối với dữ liệu được nhập thủ công, bạn vẫn không bắt buộc phải cung cấp thông tin về thiết bị. Mỗi hàm có ba biến thể chữ ký:
activelyRecordedfun activelyRecorded(device: Device): Metadata.fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadatafun activelyRecordedWithId(id: String, device: Device): Metadata
autoRecordedfun autoRecorded(device: Device): Metadatafun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadatafun autoRecordedWithId(id: String, device: Device): Metadata
manualEntryfun manualEntry(device: Device? = null): Metadatafun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadatafun manualEntryWithId(id: String, device: Device? = null): Metadata
unknownRecordingMethodfun unknownRecordingMethod(device: Device? = null): Metadatafun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadatafun unknownRecordingMethodWithId(id: String, device: Device? = null): Metadata
Để biết thêm thông tin, hãy xem Dự án nguồn mở Android.
Dữ liệu kiểm thử
Sử dụng Thư viện kiểm thử và
MetadataTestHelper để mô phỏng các giá trị siêu dữ liệu dự kiến:
private val TEST_METADATA =
Metadata.unknownRecordingMethod(
clientRecordId = "clientId",
clientRecordVersion = 1L,
device = Device(type = Device.TYPE_UNKNOWN),
).populatedWithTestValues(id = "test")
Thao tác này mô phỏng hành vi của quá trình triển khai Health Connect, tự động điền các giá trị này trong quá trình chèn bản ghi.
Đối với thư viện kiểm thử, bạn cần thêm phần phụ thuộc SDK Health Connect này vào tệp build.gradle ở cấp mô-đun:
dependencies {
testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}
Nâng cấp thư viện
Sau đây là các bước chính bạn cần thực hiện:
Nâng cấp thư viện lên phiên bản 1.1.0-alpha12.
Khi tạo thư viện, lỗi biên dịch sẽ được gửi khi cần có siêu dữ liệu mới. Để giải quyết các lỗi này và hoàn tất quá trình di chuyển, hãy xác minh rằng bạn đã thực hiện những thay đổi sau:
- Bạn bắt buộc phải chỉ định một phương thức ghi khi tạo
Record. Bạn có thể thực hiện việc này bằng cách sử dụng một trong các phương thức nhà máy được cung cấp trongMetadata, chẳng hạn nhưMetadata.manualEntry()hoặcMetadata.activelyRecorded(device = Device(...)). - Đối với dữ liệu do thiết bị ghi lại, bạn bắt buộc phải chỉ định loại thiết bị, chẳng hạn như
Device.TYPE_WATCHhoặcDevice.TYPE_PHONE.
- Bạn bắt buộc phải chỉ định một phương thức ghi khi tạo
Nếu ứng dụng của bạn ghi các loại thiết bị mở rộng, hãy kiểm soát các loại thiết bị đó bằng
FEATURE_EXTENTED_DEVICE_TYPESđể tránhTYPE_UNKNOWNngoài dự kiến trên các thiết bị không có tính năng này.