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ó 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.
Để xác định xem thiết bị của người dùng có hỗ trợ Loại thiết bị mở rộng trên Health Connect hay không, hãy kiểm tra xem 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
}
Hãy xem phần Kiểm tra phạm vi cung cấp của các tính năng để tìm hiểu thêm.

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

  • 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")

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:

  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ẽ đượ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 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 kiểm soát các loại thiết bị đó bằng FEATURE_EXTENTED_DEVICE_TYPES để tránh TYPE_UNKNOWN ngoài dự kiến trên các thiết bị không có tính năng này.