Metadata requirements

This guide is compatible with Health Connect version 1.1.0-alpha12.

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

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 ensure that additional useful metadata exists in the ecosystem.

You are required to specify metadata details whenever a Record() type object is instantiated.

You must specify one of four recording methods when writing data to Health Connect:

Recording method Description
RECORDING_METHOD_UNKNOWN The recording method cannot be verified.
RECORDING_METHOD_MANUAL_ENTRY The user entered the data.
RECORDING_METHOD_AUTOMATICALLY_RECORDED A device or sensor recorded the data.
RECORDING_METHOD_ACTIVELY_RECORDED The user initiated the start or end of the recording session on a device.

For example:

StepsRecord(
    startTime \= Instant.ofEpochMilli(1234L),
    startZoneOffset \= null,
    endTime \= Instant.ofEpochMilli(1236L),
    endZoneOffset \= null,
    metadata \= Metadata.manualEntry(),
    Count \= 10,
)

You are required to specify a device type for all automatically and actively recorded data. Current device types include:

Device type Description
TYPE_UNKNOWN The device type is unknown.
TYPE_WATCH The device type is a watch.
TYPE_PHONE The device type is a phone.
TYPE_SCALE The device type is a scale.
TYPE_RING The device type is a ring.
TYPE_HEAD_MOUNTED The device type is a head-mounted device.
TYPE_FITNESS_BAND The device type is a fitness band.
TYPE_CHEST_STRAP The device type is a chest strap.
TYPE_SMART_DISPLAY The device type is a smart display.

For example:

private val TEST_DEVICE = Device(type = Device.TYPE_PHONE)

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. 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 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, so be sure to implement the necessary metadata changes whenever a Record() type object is instantiated. This should complete the migration.