> This guide is compatible with Health Connect version [1.1.0-alpha12](https://developer.android.com/jetpack/androidx/releases/health-connect#1.1.0-alpha12).

There are changes to metadata in Health Connect for
developers who choose to upgrade to release 1.1.0-alpha12.
| **Warning:** Updating Jetpack versions without implementing these changes will break your Health Connect integration.

## Library information

The [Google Maven Android gradle plugin](https://developer.android.com/build/dependencies#google-maven) 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](https://developer.android.com/health-and-fitness/guides/health-connect/develop/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](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:health/connect/connect-client/src/main/java/androidx/health/connect/client/records/metadata/Metadata.kt).

### Testing data

Use the [Testing Library](https://developer.android.com/health-and-fitness/guides/health-connect/test/unit-tests) 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.