Настройте приложение Wear OS для Watch Face Push

Функция Watch Face Push позволяет вашему приложению управлять циферблатами на устройстве Wear OS. Это включает в себя добавление, обновление и удаление циферблатов, а также установку активного циферблата. Настройте приложение Wear OS для использования API Watch Face Push.

Настраивать

Включите необходимые зависимости:

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

Добавьте следующее в ваш AndroidManifest.xml :

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Required to use the Watch Face Push API.  -->
    <uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />

    <!-- Required to be able to call the setWatchFaceAsActive() method. -->
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />

</manifest>

Получить ссылку на экземпляр менеджера

Получите экземпляр WatchFacePushManager :

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager предоставляет доступ ко всем методам взаимодействия с Watch Face Push.

Работа со слотами

Ключевым понятием при работе с Watch Face Push являются слоты . Слоты — это способ работы с установленными циферблатами, принадлежащими вашему приложению. Система устанавливает максимальное количество слотов, которые может иметь магазин; в Wear OS 6 ограничение составляет 1.

При обновлении или удалении циферблата slotId используется для идентификации циферблата, над которым следует выполнить операцию.

Список циферблатов

Чтобы вывести список установленных циферблатов, используйте listWatchFaces() :

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

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

suspend fun isInstalled(packageName: String) = watchFacePush.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }

Добавить циферблат

Если есть доступные слоты, определяемые ответом listWatchFaces , то следует использовать метод addWatchFace() :

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

Обновить циферблат

Обновление циферблата позволяет заменить содержимое слота новым пакетом. Это может быть как обновление того же циферблата до более новой версии, так и полная замена циферблата на другой.

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

Удалить циферблат

Чтобы удалить циферблат:

// Remove the com.example.watchfacepush.green watch face.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

Это гарантирует, что ваш циферблат всегда будет виден в системном меню выбора циферблатов, на нем можно будет разместить ваш логотип на видном месте и даже кнопку для запуска приложения Marketplace на телефоне.

Проверьте, активен ли ваш циферблат

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

Чтобы определить, установлен ли на торговой площадке активный циферблат, используйте следующую логику:

val hasActiveWatchFace = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

Предоставьте циферблат по умолчанию

Функция Watch Face Push позволяет установить циферблат по умолчанию при установке приложения из Marketplace. Это само по себе не делает циферблат по умолчанию активным (см. раздел «Установка активного циферблата»), но гарантирует, что ваш циферблат будет доступен в системном окне выбора циферблатов.

Чтобы использовать эту функцию:

1. В сборке приложения Wear OS включите циферблат по умолчанию в путь: assets/default_watchface.apk

2. Добавьте следующую запись в ваш AndroidManifest.xml

   <application ...>
   <meta-data
       android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
       android:value="@string/default_wf_token" />
   

Установить активный циферблат

Функция Watch Face Push позволяет приложению Marketplace устанавливать активный циферблат.

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

Настройка активного циферблата часов — это двухэтапный процесс:

1. Получите разрешение Android, необходимое для настройки активного циферблата.
2. Вызовите метод setWatchFaceAsActive .

Получите разрешение на установку активного циферблата

Требуемое разрешение — SET_PUSHED_WATCH_FACE_AS_ACTIVE , которое необходимо добавить в ваш манифест:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

Поскольку это разрешение времени выполнения, ваше приложение должно запрашивать это разрешение у пользователя при запуске приложения (для решения этой проблемы можно воспользоваться библиотекой Accompanist ).

Установить циферблат как активный

После предоставления разрешения вызовите setWatchFaceAsActive для идентификатора слота циферблата, который должен быть активным:

watchFacePushManager.setWatchFaceAsActive(slotId)

После использования этого способа приложение на вашем телефоне должно вместо этого предложить инструкции по ручной установке активного циферблата.

Прочтите дополнительные метаданные из APK-файла вашего циферблата

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

Это может быть особенно полезно в ситуациях, когда у вас есть несколько вариантов одного и того же циферблата. Например, можно определить циферблат:

• Имя пакета: com.myapp.watchfacepush.mywatchface
• Версия пакета: 1.0.0

Но этот циферблат может поставляться в виде четырех разных APK, все из которых почти одинаковы, но с разными цветами по умолчанию: красным, желтым, зеленым и синим , установленными в ColorConfiguration в XML-файле формата циферблата часов.

Это небольшое изменение затем отражено в каждом из четырех APK:

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
        android:name="default_color"
        android:value="red" />

Использование настраиваемого свойства позволяет вашему приложению определять, какой из этих вариантов установлен:

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

Соображения

При внедрении функции Watch Face Push в ваше приложение следует обратить внимание на энергопотребление, кэширование, обновление встроенных циферблатов и предоставление репрезентативного циферблата по умолчанию.

Власть

Ключевым фактором для любого приложения, работающего на Wear OS, является энергопотребление. Для компонента Wear OS вашего приложения Marketplace:

1. Ваше приложение должно запускаться как можно реже и реже (за исключением случаев прямого взаимодействия пользователя с ним). Это включает в себя:
   • Минимизация пробуждения приложения из приложения «Телефон»
   • Минимизация выполнения заданий WorkManager
2. Запланируйте создание аналитических отчетов на время зарядки часов :
   1. Если вы хотите предоставить статистику использования из приложения Wear OS или любые другие показатели, используйте WorkManager с ограничением requiresCharging .
3. Запланируйте обновления на время зарядки часов и использования Wi-Fi :
   1. Возможно, вам захочется проверить версии установленных циферблатов и автоматически обновить их. Опять же, используйте ограничение requiresCharging и тип сети UNMETERED для requiresNetworkType .
   2. Во время зарядки устройство, скорее всего, имеет доступ к Wi-Fi. Подключитесь к Wi-Fi, чтобы быстро загрузить обновлённые APK-файлы, и отключите сеть после завершения.
   3. Это же правило действует и в случае, если торговая площадка предлагает циферблат дня ; предварительно загрузите его, пока часы заряжаются.
4. Не планируйте задания, чтобы проверить активный циферблат :
   1. Периодическая проверка наличия активного циферблата на вашем устройстве и его типа приводит к быстрому разряду аккумулятора. Избегайте этого подхода.
5. Не используйте уведомления на часах :
   1. Если ваше приложение использует уведомления, сосредоточьте их на телефоне, где действие пользователя открывает телефонное приложение для продолжения работы. Убедитесь, что уведомления не перенаправляются в приложение часов с помощью setLocalOnly .

Кэширование

В примере с канонической торговой площадкой циферблаты переносятся с телефона на часы. Обычно это соединение по Bluetooth, которое может быть довольно медленным.

Чтобы обеспечить лучший пользовательский опыт и сэкономить мощность повторной передачи, рассмотрите возможность внедрения небольшого кэша в устройство Wear OS для хранения нескольких APK-файлов.

В случае, когда пользователь пробует другой циферблат, а затем решает вернуться к ранее выбранному циферблату, это действие происходит практически мгновенно.

Аналогичным образом это можно использовать для предварительного кэширования циферблата дня или аналогичных схем, когда циферблаты загружаются во время зарядки устройства Wear OS.

Обновление циферблатов в комплекте

Ваше приложение может включать в себя циферблат по умолчанию, как описано ранее. Важно понимать, что, хотя этот циферблат устанавливается в систему при установке вашего приложения из Marketplace, он не обновляется при установке новой версии вместе с любым обновлением вашего приложения из Marketplace.

Чтобы справиться с этой ситуацией, ваше приложение Marketplace должно прослушивать широковещательное действие MY_PACKAGE_REPLACED и проверять необходимость обновления любого связанного циферблата из ресурсов пакета.

Репрезентативный циферблат по умолчанию

Циферблат по умолчанию — отличный способ помочь пользователям найти и использовать ваш магазин: циферблат устанавливается вместе с вашим магазином, поэтому пользователи могут найти его в галерее циферблатов.

Некоторые соображения по работе с циферблатами по умолчанию:

• Не используйте removeWatchFace , если пользователь решит удалить циферблат из вашего приложения Marketplace. Вместо этого верните циферблат к стандартному с помощью updateWatchFace . Это поможет пользователям найти ваш циферблат и установить его из галереи.
• Сделайте циферблат по умолчанию простым и легко узнаваемым благодаря логотипу и темам. Это поможет пользователям найти его в галерее циферблатов.

• Добавьте кнопку на циферблат по умолчанию для открытия приложения «Телефон». Это можно сделать в два этапа:

  1. Добавьте элемент Launch на циферблат часов, чтобы запустить намерение с помощью приложения Wear OS, например:

     <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />

  2. В LaunchOnPhoneActivity запустите приложение телефона с помощью RemoteActivityHelper .