This document describes how to synchronize data between a Wear OS device and a handheld device.

## Send and sync data directly from the network

Build Wear OS apps to[communicate directly with the network](https://developer.android.com/training/wearables/data-layer/network-access). Use the same APIs that you use for mobile development, but keep some Wear-OS-specific differences in mind.

## Synchronize data using the Wear OS Data Layer API

A`DataClient`exposes an API for components to read or write to a`DataItem`or`Asset`.
| **Note:** The class is meant to transfer data and not serve as a storage mechanism. Create your own copy of the data that your app can access, such as in a[Room database](https://developer.android.com/training/data-storage/room).

It's possible to set data items and assets while not connected to any devices. They're synchronized when the devices establish a network connection. This data is private to your app and is only accessible to your app on other devices.

- A`DataItem`is synchronized across all devices in a Wear OS network. They're generally small in size.

  | **Note:** When an app is uninstalled on the phone, data items and assets are reset.
- Use an`Asset`to transfer a larger object, such as an image. The system keeps track of which assets have already been transferred and performs deduplication automatically.

### Listen for events in services

Extend the[`WearableListenerService`](https://developers.google.com/android/reference/com/google/android/gms/wearable/WearableListenerService)class. The system manages the lifecycle of the base`WearableListenerService`, binding to the service when it needs to send data items or messages and unbinding the service when no work is needed.

### Listen for events in activities

Implement the[`OnDataChangedListener`](https://developers.google.com/android/reference/com/google/android/gms/wearable/DataClient.OnDataChangedListener)interface. Use this interface instead of a`WearableListenerService`when you want to listen for changes only when the user is actively using your app.

## Transfer data

To send binary large objects over the Bluetooth transport, such as a voice recording from another device, you can attach an[`Asset`](https://developers.google.com/android/reference/com/google/android/gms/wearable/Asset)to a data item and then put the data item into the replicated datastore.
| **Note:**The Data Layer API can send messages and synchronize data only with Android phones or Wear OS watches. If a Wear OS device is paired with an iOS device, the Data Layer API won't work.
|
| For this reason, don't use the Data Layer API as the primary way to communicate with a network. Instead, follow the same pattern in your Wear app as in a mobile app---with some minor differences, as described in[Network access and sync on Wear OS](https://developer.android.com/training/wearables/data-layer/network-access).

Assets automatically handle caching of data to prevent retransmission and to conserve Bluetooth bandwidth. A common pattern is for a handheld app to download an image, shrink it to an appropriate size for display on the wearable, and transmit it to the wearable app as an asset. The following examples demonstrate this pattern.

**Note:**Although the size of data items is theoretically limited to 100 KB, in practice larger data items can be used. For larger data items, separate data by unique paths and avoid using a single path for all data. Transferring large assets affects the user experience in many cases, so test your apps to help ensure that they perform well when transferring large assets.

### Transfer an asset

Create the asset using one of the`create...()`methods in the[`Asset`](https://developers.google.com/android/reference/com/google/android/gms/wearable/Asset.html)class. Convert a bitmap to a byte stream and then call[`createFromBytes()`](https://developers.google.com/android/reference/com/google/android/gms/wearable/Asset.html#createFromBytes(byte[]))to create the asset, as shown in the following sample.  

### Kotlin

```kotlin
private fun createAssetFromBitmap(bitmap: Bitmap): Asset =
    ByteArrayOutputStream().let { byteStream ->
        bitmap.compress(Bitmap.CompressFormat.PNG, 100, byteStream)
        Asset.createFromBytes(byteStream.toByteArray())
    }
```

### Java

```java
private static Asset createAssetFromBitmap(Bitmap bitmap) {
    final ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
    bitmap.compress(Bitmap.CompressFormat.PNG, 100, byteStream);
    return Asset.createFromBytes(byteStream.toByteArray());
}
```

Next, attach the asset to a data item with the`putAsset()`method in[`DataMap`](https://developers.google.com/android/reference/com/google/android/gms/wearable/DataMap.html)or[`PutDataRequest`](https://developers.google.com/android/reference/com/google/android/gms/wearable/PutDataRequest.html). Then put the data item into the datastore using the[`putDataItem()`](https://developers.google.com/android/reference/com/google/android/gms/wearable/DataApi.html#putDataItem(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.wearable.PutDataRequest))method, as shown in the following samples.

The following sample uses`PutDataRequest`:  

### Kotlin

```kotlin
val asset: Asset = BitmapFactory.decodeResource(resources, R.drawable.image).let { bitmap ->
    createAssetFromBitmap(bitmap)
}
val request: PutDataRequest = PutDataRequest.create("/image").apply {
    putAsset("profileImage", asset)
}
val putTask: Task<DataItem> = Wearable.getDataClient(context).putDataItem(request)
```

### Java

```java
Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.image);
Asset asset = createAssetFromBitmap(bitmap);
PutDataRequest request = PutDataRequest.create("/image");
request.putAsset("profileImage", asset);
Task<DataItem> putTask = Wearable.getDataClient(context).putDataItem(request);
```

<br />

The following sample uses`PutDataMapRequest`:  

### Kotlin

```kotlin
val asset: Asset = BitmapFactory.decodeResource(resources, R.drawable.image).let { bitmap ->
    createAssetFromBitmap(bitmap)
}
val request: PutDataRequest = PutDataMapRequest.create("/image").run {
    dataMap.putAsset("profileImage", asset)
    asPutDataRequest()
}
val putTask: Task<DataItem> = Wearable.getDataClient(context).putDataItem(request)
```

### Java

```java
Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.image);
Asset asset = createAssetFromBitmap(bitmap);
PutDataMapRequest dataMap = PutDataMapRequest.create("/image");
dataMap.getDataMap().putAsset("profileImage", asset);
PutDataRequest request = dataMap.asPutDataRequest();
Task<DataItem> putTask = Wearable.getDataClient(context).putDataItem(request);
```

<br />

| **Caution:** Before using the Wearable Data Layer API, check that it's available on a device; otherwise, an exception occurs. Use the[`GoogleApiAvailability`](https://developers.google.com/android/reference/com/google/android/gms/common/GoogleApiAvailability)class, as implemented in[Horologist](https://github.com/google/horologist/blob/release-0.5.x/datalayer/core/src/main/java/com/google/android/horologist/data/WearableApiAvailability.kt#L29).

### Receive assets

When an asset is created, you probably want to read and extract it on other side of the connection. Here's an example of how to implement the callback to detect an asset change and extract the asset:  

### Kotlin

```kotlin
override fun onDataChanged(dataEvents: DataEventBuffer) {
    dataEvents
            .filter { it.type == DataEvent.TYPE_CHANGED && it.dataItem.uri.path == "/image" }
            .forEach { event ->
                val bitmap: Bitmap? = DataMapItem.fromDataItem(event.dataItem)
                        .dataMap.getAsset("profileImage")
                        .let { asset -> loadBitmapFromAsset(asset) }
                // Do something with the bitmap
            }
}

fun loadBitmapFromAsset(asset: Asset): Bitmap? {
    // Convert asset into a file descriptor and block until it's ready
    val assetInputStream: InputStream? =
            Tasks.await(Wearable.getDataClient(context).getFdForAsset(asset))
            ?.inputStream

    return assetInputStream?.let { inputStream ->
        // Decode the stream into a bitmap
        BitmapFactory.decodeStream(inputStream)
    } ?: run {
        Log.w(TAG, "Requested an unknown Asset.")
        null
    }
}
```

### Java

```java
@Override
public void onDataChanged(DataEventBuffer dataEvents) {
  for (DataEvent event : dataEvents) {
    if (event.getType() == DataEvent.TYPE_CHANGED &&
        event.getDataItem().getUri().getPath().equals("/image")) {
      DataMapItem dataMapItem = DataMapItem.fromDataItem(event.getDataItem());
      Asset profileAsset = dataMapItem.getDataMap().getAsset("profileImage");
      Bitmap bitmap = loadBitmapFromAsset(profileAsset);
      // Do something with the bitmap
    }
  }
}

public Bitmap loadBitmapFromAsset(Asset asset) {
    if (asset == null) {
        throw new IllegalArgumentException("Asset must be non-null");
    }
    // Convert asset into a file descriptor and block until it's ready
    InputStream assetInputStream =
        Tasks.await(Wearable.getDataClient(context).getFdForAsset(asset))
            .getInputStream();
    if (assetInputStream == null) {
        Log.w(TAG, "Requested an unknown Asset.");
        return null;
    }
    // Decode the stream into a bitmap
    return BitmapFactory.decodeStream(assetInputStream);
}
```

For more information, see the[DataLayer sample project](https://github.com/android/wear-os-samples/tree/main/DataLayer)on GitHub.