Yêu cầu về siêu dữ liệu

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ó những thay đổi đối với siêu dữ liệu trong Health Connect dành cho những 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ã nhận dạng cấu phần phần mềm trình bổ trợ gradle Android 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 giới thiệu trong 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ó trong hệ sinh thái. Nếu metadata không có trong hàm khởi tạo Record, bạn có thể gặp 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 4 phương thức ghi bằng cách sử dụng một trong các phương thức tạo tương ứng để khởi tạo Metadata:

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
)
HealthConnectManager.kt

Loại thiết bị

Bạn phải chỉ định một loại thiết bị cho tất cả dữ liệu được ghi 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:

Một số giá trị Device.type chỉ có trong 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 dùng được, các loại này sẽ được coi là Device.TYPE_UNKNOWN.

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
)
HealthConnectManager.kt

Giá trị 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 có hỗ trợ Mã 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ô hình 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ố ở cấp độ lâm sàng và phân biệt chúng 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 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 khi bắt đầu 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 bao gồm 2 phần:

• Giá trị nhận dạng thiết bị (UDI-DI): Giá trị nhận dạng được công nhận trên toàn cầu do một cơ quan phát hành chỉ định cho một mẫu thiết bị cụ thể (ví dụ: GS1).
• Giá trị nhận dạng sản phẩm (UDI-PI): Các thuộc tính dành riêng cho từng đơ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.

val device = Device(
    type = Device.TYPE_CONSUMER_MEDICAL_DEVICE,
    manufacturer = "Omron",
    model = "HEM-7121",
    udi = "04015674011832" // Device Identifier (UDI-DI) portion only
)

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 bằng UDI mà không khai báo quyền WRITE_DEVICE_UDI, Health Connect sẽ gửi một SecurityException tại thời điểm ghi.

Sử dụng UDI để xác minh việc xoá dữ liệu trên thiết bị

Health Connect đóng vai trò là một lớp 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 các trình đọc dữ liệu, sự hiện diện của một UDI cho biết dữ liệu có nguồn gốc từ một thiết bị y tế đã đăng ký. Các ứng dụng đọc nên truy vấn cơ sở dữ liệu quy định như Cơ sở dữ liệu toàn cầu về giá trị nhận dạng duy nhất của thiết bị (GUDID) của FDA hoặc EUDAMED của Liên minh Châu Âu để xác minh phân loại thiết bị, trạng thái cấp phép 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

Chúng tôi đã cập nhật các hướng dẫn về Health Connect ở 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.

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ể siêu dữ liệu nữa, vì vậy, hãy dùng một trong các phương thức của nhà máy để lấy thực thể siêu dữ liệu mới. Các phương thức của nhà máy xác minh rằng thông tin thiết bị được cung cấp khi một 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 theo cách thủ công, bạn không bắt buộc phải cung cấp thông tin về thiết bị. Mỗi hàm có 3 biến thể chữ ký:

• activelyRecorded

  • fun activelyRecorded(device: Device): Metadata.
  • fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun activelyRecordedWithId(id: String, device: Device): Metadata

• autoRecorded

  • fun autoRecorded(device: Device): Metadata
  • fun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun autoRecordedWithId(id: String, device: Device): Metadata

• manualEntry

  • fun manualEntry(device: Device? = null): Metadata
  • fun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun manualEntryWithId(id: String, device: Device? = null): Metadata

• unknownRecordingMethod

  • fun unknownRecordingMethod(device: Device? = null): Metadata
  • fun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun 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")

Điều này mô phỏng hành vi của việc 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

Các bước chính bạn cần thực hiện là:

1. Nâng cấp thư viện lên phiên bản 1.1.0-alpha12.

2. Khi tạo thư viện, lỗi biên dịch sẽ xảy ra khi cần có siêu dữ liệu mới. Để giải quyết những 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 của nhà máy có trong Metadata, chẳng hạn như Metadata.manualEntry() hoặc Metadata.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_WATCH hoặc Device.TYPE_PHONE.

3. Nếu ứng dụng của bạn ghi các loại thiết bị mở rộng, hãy đặt chúng sau FEATURE_EXTENTED_DEVICE_TYPES để tránh TYPE_UNKNOWN không mong muốn trên những thiết bị không có tính năng này.