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

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

Настраивать

Добавьте зависимость androidx.wear.watchfacepush:watchfacepush в файл build.gradle.kts .

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

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

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

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

val watchFacePushManager = WatchFacePushManagerFactory.createWatchFacePushManager(context)
WatchFacePush.kt

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

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

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

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

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

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

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
installedList.forEach {
    Log.i(TAG, "Installed watchface: ${it.packageName}")
}

val remainingSlots = response.remainingSlotCount
Log.i(TAG, "Remaining slots: $remainingSlots")
WatchFacePush.kt

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

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

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

Если, согласно ответу 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: WatchFacePushManager.AddWatchFaceException) {
    Log.e(TAG, "Something went wrong installing the watch face", e)
}
WatchFacePush.kt

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

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

// 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
        ?: throw IllegalArgumentException("No green watch face found")
try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: WatchFacePushManager.UpdateWatchFaceException) {
    Log.e(TAG, "Something went wrong updating the watch face", e)
}
WatchFacePush.kt

Удалить циферблат часов

Чтобы снять циферблат:

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

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: WatchFacePushManager.RemoveWatchFaceException) {
    Log.e(TAG, "Something went wrong removing the watch face", e)
}
WatchFacePush.kt

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

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

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

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

suspend fun hasActiveWatchFace() = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }
WatchFacePush.kt

Укажите циферблат часов по умолчанию

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

Для использования этой функции:

1. В сборке вашего приложения для Wear OS добавьте стандартный циферблат в путь: assets/default_watchface.apk

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

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

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

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

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

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

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

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

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

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

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

Установите циферблат в качестве активного.

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

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

Прочитайте дополнительные метаданные из 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" />
AndroidManifest.xml

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

val color = watchFaceDetails
    .getMetaData("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()
Log.i(TAG, "Default color: $color")
WatchFacePush.kt

Соображения

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

Власть

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

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.

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

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

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

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

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

Некоторые моменты, которые следует учитывать при работе со стандартными циферблатами:

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

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

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

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

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