Metadata requirements

This guide is compatible with Health Connect version 1.2.0-alpha05 and later.

There are changes to metadata in Health Connect for developers who upgrade to release 1.1.0-alpha12 or later.

Library information

The Google Maven Android gradle plugin artifact ID identifies the Health Connect library to which you will need to upgrade. Add this Health Connect SDK dependency to your module-level build.gradle file:

dependencies {
  implementation "androidx.health.connect:connect-client:1.1.0-alpha12"
}

Metadata changes

Two metadata changes have been introduced to the Health Connect Jetpack SDK as of version 1.1.0-alpha12 to help verify that additional useful metadata exists in the ecosystem. If metadata is not included in your Record constructor, you might see a Constructor internal error.

Specify the recording method

You must specify metadata details whenever a Record() type object is instantiated.

When writing data to Health Connect, you must specify one of four recording methods by using one of the corresponding factory methods to instantiate Metadata:

For example:

 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

Device type

You must specify a device type for all automatically and actively recorded data. For more details, see the Device class in the Jetpack documentation. Current device types include:

Some Device.type values are only available on later versions of Health Connect. When the extended device types feature isn't available, these types are treated as Device.TYPE_UNKNOWN.

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

  // Feature is available
} else {
  // Feature isn't available
}

For example:

 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

Unique Device Identifier (UDI)

For Health Connect on Android 17 (API level 37.1) or U extension 23 or later, the Device class includes support for the Unique Device Identifier (UDI). Associating a medical device's registered UDI model details with your written records allows downstream applications (such as telehealth platforms or clinical portals) to identify clinical-grade readings and distinguish them from general consumer-wearable data.

Declare the permission

To write UDI details to Health Connect, you must declare the WRITE_DEVICE_UDI permission in your app's AndroidManifest.xml file:

<uses-permission android:name="android.permission.health.WRITE_DEVICE_UDI" />

Note that WRITE_DEVICE_UDI is a normal permission. You must declare it in your manifest, but you don't need to request it from the user at runtime. It's automatically granted to your app at install time.

Write only the Device Identifier (DI) portion

A complete UDI contains two parts:

• Device Identifier (UDI-DI): A globally recognized identifier assigned to a specific device model by an issuing agency (for example, GS1).
• Production Identifier (UDI-PI): Unit-specific attributes, such as serial numbers, batch numbers, manufacturing dates, or expiration dates.

To protect user privacy, only populate the UDI-DI portion of the code in Health Connect. Don't include any production identifier attributes (such as serial numbers or batch numbers).

Code example

Note: You can set the UDI when constructing a Device instance.

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()

If you write data with a UDI without declaring the WRITE_DEVICE_UDI permission, Health Connect throws a SecurityException at write time.

Use UDI to verify device clearance

Health Connect serves as a transport layer and does not validate the authenticity or registration status of the UDI.

For data readers, the presence of a UDI indicates that the data originates from a registered medical device. Reading apps should query regulatory databases like the FDA's Global Unique Device Identification Database (GUDID) or the EU's EUDAMED to verify device classifications, regulatory clearance status (for example, Class I, II, or III), or specific intended use.

Snippets updated

Health Connect guides have been updated wherever new snippets are needed to adhere to the new metadata requirements. For some examples, refer to the Write Data page.

New metadata methods

Metadata can no longer be directly instantiated, so use one of the factory methods to get a new instance of metadata. The factory methods verify that device information is provided when a device or sensor was used to record the data. For manually entered data, providing device information remains optional. Each function has three signature variants:

• 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

For more information, see the Android Open Source Project.

Testing data

Use the Testing Library and MetadataTestHelper to mock expected metadata values:

private val TEST_METADATA =
    Metadata.unknownRecordingMethod(
        clientRecordId = "clientId",
        clientRecordVersion = 1L,
        device = Device(type = Device.TYPE_UNKNOWN),
    ).populatedWithTestValues(id = "test")

This simulates the behavior of the Health Connect implementation, which automatically populates these values during record insertion.

For the testing library, you need to add this Health Connect SDK dependency to your module-level build.gradle file:

dependencies {
  testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}

Upgrade the library

The main steps you need to perform are:

1. Upgrade your library to 1.1.0-alpha12.

2. When building the library, compilation errors will be thrown where new metadata is needed. To resolve these errors and complete migration, verify you make the following changes:

   • It is mandatory to specify a recording method when constructing a Record. This is done by using one of the factory methods provided in Metadata, such as Metadata.manualEntry() or Metadata.activelyRecorded(device = Device(...)).
   • For data recorded by a device, it is mandatory to specify a device type, such as Device.TYPE_WATCH or Device.TYPE_PHONE.

3. If your app writes extended device types, gate them behind FEATURE_EXTENTED_DEVICE_TYPES to avoid unexpected TYPE_UNKNOWN on devices where the feature isn't available.