Эта страница переведена с помощью Cloud Translation API.

Настройте приложение Wear OS для Watch Face Push
Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Настраивать

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

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

Добавьте следующее в ваш 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 = WatchFacePushManager(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 на телефоне.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Получите разрешение Android, необходимое для настройки активного циферблата.
Вызовите метод 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:

Ваше приложение должно запускаться как можно реже и реже (если только с ним не взаимодействует напрямую пользователь). Это включает в себя:
- Минимизация пробуждения приложения из приложения телефона
- Минимизация выполнения заданий WorkManager
Запланируйте создание аналитических отчетов на время зарядки часов :
1. Если вы хотите получить статистику использования из приложения Wear OS или любые другие показатели, используйте WorkManager с ограничением requiresCharging .
Запланируйте обновления на время зарядки часов и использования WiFi :
1. Вы можете проверить версии установленных циферблатов и автоматически обновить их. Опять же, используйте ограничение requiresCharging и тип сети UNMETERED для requiresNetworkType .
2. При зарядке устройство, скорее всего, имеет доступ к Wi-Fi. Запросите Wi-Fi, чтобы быстро загрузить обновленные APK, и отключите сеть, когда закончите.
3. Это же правило действует и в случае, если на торговой площадке предлагается циферблат дня ; предварительно загрузите его, пока часы заряжаются.
Не планируйте задания для проверки активного циферблата :
1. Периодическая проверка того, есть ли на вашем рынке еще активный циферблат и какой это циферблат, приводит к разрядке батареи. Избегайте этого подхода.
Не используйте уведомления на часах :
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 .