Как синхронизировать объекты данных с помощью Data Layer API

DataItem определяет интерфейс, который система использует для синхронизации данных между портативными и носимыми устройствами. DataItem обычно состоит из следующих компонентов:

  • Полезная нагрузка. Массив байтов, который можно задать с помощью данных, что позволяет выполнять сериализацию и десериализацию объектов. Размер полезной нагрузки ограничен 100 КБ.
  • Путь. Уникальная строка, которая должна начинаться с косой черты, например "/path/to/data".

Примечание. Data Layer API может отправлять сообщения и синхронизировать данные только с телефонами Android и часами Wear OS. Если устройство Wear OS подключено к iOS-устройству, Data Layer API работать не будет.

По этой причине не используйте Data Layer API в качестве основного способа связи с сетью. Вместо этого следуйте той же схеме, что и для мобильного приложения, с некоторыми незначительными отличиями.

Обычно вы не реализуете DataItem напрямую. Вместо этого выполните следующие действия:

  1. Создайте объект PutDataRequest, указав строковый путь, который однозначно идентифицирует объект.
  2. Вызовите метод setData(), чтобы задать полезную нагрузку.
  3. Если задержка синхронизации может негативно повлиять на удобство использования, вызовите setUrgent().
  4. Используйте метод putDataItem класса DataClient, чтобы запросить у системы создание элемента данных.

При запросе элементов данных система возвращает объекты, которые правильно реализуют интерфейс DataItem. Однако вместо того, чтобы работать с необработанными байтами с помощью setData(), мы рекомендуем использовать карту данных, которая предоставляет доступ к элементу данных с интерфейсом, похожим на Bundle.

Подробнее о приложении DataLayer Sample…

Как синхронизировать данные с картой данных

По возможности используйте класс DataMap. Этот подход позволяет работать с элементами данных в виде объекта Bundle Android, поэтому система выполняет сериализацию и десериализацию объектов за вас, и вы можете манипулировать данными с помощью пар "ключ-значение".

Чтобы использовать карту данных:

  1. Создайте объект PutDataMapRequest, указав путь к элементу данных.

    Примечание. Строка пути – это уникальный идентификатор объекта данных, который позволяет получить доступ к нему с любой стороны подключения. Путь должен начинаться с косой черты. Если в вашем приложении используются иерархические данные, создайте схему пути, соответствующую структуре данных.

  2. Вызывайте метод PutDataMapRequest.getDataMap(), чтобы получить карту данных, в которой можно задавать значения.
  3. Задайте значения для карты данных, используя методы put...(), например: putString().
  4. Если задержка синхронизации может негативно повлиять на удобство использования, вызовите метод setUrgent().
  5. Вызовите PutDataMapRequest.asPutDataRequest(), чтобы получить объект PutDataRequest.
  6. Используйте метод putDataItem класса DataClient, чтобы запросить у системы создание элемента данных.

    Примечание. Если мобильный телефон и носимые устройства отключены друг от друга, данные буферизуются и синхронизируются при восстановлении подключения.

В следующем примере метод increaseCounter() показывает, как создать карту данных и добавить в нее данные:

private fun increaseCounter(): Task<DataItem> {
    val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
        dataMap.putInt(COUNT_KEY, count++)
        asPutDataRequest()
    }
    return Wearable.getDataClient(this)
        .putDataItem(putDataReq)
}

Подробнее об обработке Tasks рассказывается в справочной документации.

Внимание! Перед использованием Wearable Data Layer API убедитесь, что он доступен на устройстве. В противном случае возникнет исключение. Используйте класс GoogleApiAvailability, реализованный в Horologist.

Как задать приоритет объекта DataItem

API DataClient позволяет отправлять срочные запросы на синхронизацию объектов DataItem. Обычно система задерживает передачу данных в сеть Wear OS, чтобы увеличить время работы от батареи на устройствах пользователей. Однако если задержка синхронизации данных негативно влияет на удобство использования, вы можете пометить их как срочные. Например, в приложении для дистанционного управления, где пользователь ожидает, что его действия будут отражены немедленно, вы можете синхронизировать объекты данных, вызвав метод setUrgent().

Если вы не вызовете setUrgent(), система может отложить синхронизацию некритичных данных на срок до 30 минут, хотя обычно задержка составляет всего несколько минут. По умолчанию используется срочность "не срочно", поэтому, если вам нужно сохранить поведение немедленной синхронизации из предыдущих версий Wear OS API, используйте setUrgent().

Как отслеживать события элементов данных

Если одна из сторон подключения к уровню данных изменяет элемент данных, уведомляйте пользователя о любых изменениях на другой стороне подключения. Для этого нужно реализовать прослушиватель событий объектов данных.

Приведенный ниже фрагмент кода уведомляет приложение об изменении значения счетчика, определенного в предыдущем примере:

override fun onDataChanged(dataEvents: DataEventBuffer) {

    dataEvents.forEach { event ->
        // DataItem changed
        if (event.type == DataEvent.TYPE_CHANGED) {
            event.dataItem.also { item ->
                if (item.uri.path?.compareTo("/count") == 0) {
                    DataMapItem.fromDataItem(item).dataMap.apply {
                        updateCount(getInt(COUNT_KEY))
                    }
                }
            }
        } else if (event.type == DataEvent.TYPE_DELETED) {
            // DataItem deleted
        }
    }
}

В этом действии реализован интерфейс DataClient.OnDataChangedListener. Объект activity добавляет себя в качестве прослушивателя событий элемента данных в методе onResume() и удаляет прослушиватель в методе onPause(). Пример реализации с использованием изображений, моделей и сервисов можно найти в приложении DataLayer Sample.

Вы также можете реализовать прослушиватель как сервис. Подробнее о том, как отслеживать события на уровне данных…