Cómo configurar tu app para Wear OS para enviar caras de reloj

El envío de caras de reloj permite que tu app administre caras de reloj en un dispositivo Wear OS. Esto incluye agregar, actualizar y quitar caras de reloj, así como configurar la cara de reloj activa. Configura tu app para Wear OS para que use la API de Push de Caras de Relojes.

Configuración

Incluye las dependencias necesarias:

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

Agrega lo siguiente a tu 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>

Obtén una referencia a la instancia del administrador

Obtén una instancia de WatchFacePushManager:

val manager = WatchFacePushManager(context)

WatchFacePushManager proporciona acceso a todos los métodos para interactuar con el envío de caras de reloj.

Trabaja con ranuras

Un concepto clave cuando se trabaja con la función Push de caras de reloj son los slots. Los espacios son una forma de abordar las caras de reloj instaladas que pertenecen a tu aplicación. El sistema configura una cantidad máxima de ranuras que puede tener un mercado. Con Wear OS 6, el límite es de 1.

Cuando se actualiza o quita una cara de reloj, se usa slotId para identificar la cara de reloj en la que se realizará la operación.

Cómo ver una lista de caras de reloj

Para enumerar el conjunto de caras de reloj instaladas, usa listWatchFaces():

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

Esto te permite determinar si el espacio está disponible o si agregar otra cara de reloj requiere reemplazar la existente. La lista también te brinda detalles sobre la cara de reloj instalada. Por ejemplo, para verificar si un paquete de cara de reloj determinado está instalado, haz lo siguiente:

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

Cómo agregar una cara de reloj

Si hay espacios disponibles, según lo determine la respuesta listWatchFaces, se debe usar el método 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.
}

Cómo actualizar una cara de reloj

La actualización de una cara de reloj te permite reemplazar el contenido de una ranura determinada por un paquete nuevo. Esto puede ser actualizar la misma cara de reloj a una versión más reciente o reemplazarla por completo por otra.

// 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.
}

Cómo quitar una cara de reloj

Para quitar una cara de reloj, haz lo siguiente:

// 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.
}

Esto garantizará que tu cara de reloj siempre se pueda encontrar en el selector de caras de reloj del sistema, que se muestre tu logotipo de forma destacada y que incluso se pueda mostrar un botón para iniciar tu app de Marketplace en el teléfono.

Cómo verificar si tu cara de reloj está activa

Determinar si tu mercado tiene configurada la cara de reloj activa es importante para garantizar que el usuario tenga una experiencia fluida: si el mercado ya tiene configurada la cara de reloj activa, si el usuario desea elegir otra cara de reloj, solo debe reemplazar la actual a través de la app del mercado para que esto tenga efecto. Sin embargo, si el mercado no tiene configurado el rostro de reloj activo, la app para teléfonos debe ofrecer al usuario más orientación. Consulta la sección sobre la app para teléfonos para obtener más detalles sobre cómo controlar esta experiencia del usuario.

Para determinar si el mercado tiene configurada la cara de reloj activa, haz lo siguiente:

Proporciona una cara de reloj predeterminada

El envío de caras de reloj ofrece la posibilidad de instalar una cara de reloj predeterminada cuando se instala tu app del mercado. Esto no configura la cara de reloj predeterminada como activa (consulta cómo configurar la cara de reloj activa), pero garantiza que tu cara de reloj esté disponible en el selector de caras de reloj del sistema.

Para usar esta función, haz lo siguiente:

  1. En la compilación de tu app para Wear OS, incluye la cara de reloj predeterminada en la ruta de acceso: assets/default_watchface.apk

  2. Agrega la siguiente entrada a tu AndroidManifest.xml

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

Cómo establecer la cara de reloj activa

El envío de caras de reloj proporciona los medios para que la app del mercado establezca la cara de reloj activa.

Esto significa, específicamente, que la app puede establecer la cara de reloj activa en una que pertenezca al mercado en el caso de que la cara de reloj activa actual no pertenezca al mercado. Ten en cuenta que, en el caso de que el mercado ya tenga la cara de reloj activa, el cambio a otra se realiza mediante una llamada a updateWatchFace para reemplazar el contenido del espacio de la cara de reloj por otra.

La configuración de la cara de reloj activa es un proceso de dos etapas:

  1. Adquiere el permiso de Android necesario para configurar la cara de reloj activa.
  2. Llama al método setWatchFaceAsActive.

Adquiere permisos para establecer la cara de reloj activa

El permiso necesario es SET_PUSHED_WATCH_FACE_AS_ACTIVE, que se debe agregar a tu manifiesto:

<?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>

Como se trata de un permiso de tiempo de ejecución, tu app debe solicitarle este permiso al usuario cuando se ejecute (considera la biblioteca Accompanist para ayudarte con esto).

Cómo establecer la cara de reloj como activa

Una vez que se otorgue el permiso, llama a setWatchFaceAsActive en el ID de la ranura de la cara de reloj que debería estar activa:

watchFacePushManager.setWatchFaceAsActive(slotId)

Una vez que se haya usado este método, la app para teléfonos debería ofrecer orientación sobre cómo configurar manualmente la cara de reloj activa.

Lee metadatos adicionales del APK de tu cara de reloj

El objeto WatchFaceSlot también proporciona los medios para obtener información adicional que puedes declarar en tu cara de reloj.

Esto puede ser útil, en particular, en situaciones en las que tienes variantes menores de la misma cara de reloj. Por ejemplo, podrías tener una cara de reloj definida de la siguiente manera:

  • Package name: com.myapp.watchfacepush.mywatchface
  • Versión del paquete: 1.0.0

Sin embargo, esta cara de reloj puede venir como cuatro APK diferentes, en los que todos son casi exactamente iguales, pero con diferentes colores predeterminados: rojo, amarillo, verde y azul, establecidos en un ColorConfiguration en el archivo en formato XML de la cara de reloj.

Esta ligera variación se refleja en cada uno de los cuatro APKs:

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

El uso de una propiedad personalizada permite que tu app determine cuál de estas variantes está instalada:

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

Consideraciones

Entre las consideraciones importantes para implementar la función Push de caras de reloj en tu app, se incluyen enfocarse en el consumo de energía, el almacenamiento en caché, la actualización de las caras de reloj empaquetadas y la proporcionación de una cara de reloj predeterminada representativa.

Energía

Una consideración clave para cualquier app que se ejecute en Wear OS es el consumo de energía. Para el componente de Wear OS de tu app de mercado, haz lo siguiente:

  1. Tu app debe ejecutarse lo menos posible y con la menor frecuencia posible (a menos que el usuario interactúe directamente con ella). Esto incluye lo siguiente:
    • Minimiza el despertar de la app desde la app de teléfono
    • Minimiza la ejecución de trabajos de WorkManager
  2. Programa los informes de estadísticas para que se generen cuando el reloj esté cargando:
    1. Si deseas informar estadísticas de uso de la app para Wear OS o cualquier otra métrica, usa WorkManager con la restricción requiresCharging.
  3. Programa las actualizaciones para que se realicen cuando el reloj se esté cargando y usa Wi-Fi:
    1. Te recomendamos que verifiques las versiones de las caras de reloj instaladas y las actualices automáticamente. Una vez más, usa la restricción requiresCharging y el tipo de red UNMETERED para requiresNetworkType.
    2. Cuando se carga, es probable que el dispositivo tenga acceso a Wi-Fi. Solicita Wi-Fi para descargar rápidamente los APKs actualizados y libera la red cuando termines.
    3. Esta misma guía se aplica cuando el mercado ofrece una cara de reloj del día. Predescárgala mientras el reloj se carga.
  4. No programes tareas para verificar la cara de reloj activa:
    1. Comprobar periódicamente si tu mercado aún tiene la cara de reloj activa y cuál es la que agota la batería Evita este enfoque.
  5. No uses notificaciones en el reloj:
    1. Si tu app usa notificaciones, enfócalas en el teléfono, donde la acción del usuario abre la app del teléfono para continuar el recorrido. Asegúrate de que no se conecten a la app de reloj con setLocalOnly.

Almacenamiento en caché

En el ejemplo de mercado canónico, las caras de reloj se transfieren del teléfono al reloj. Por lo general, esta conexión es Bluetooth, que puede ser bastante lenta.

Para proporcionar una mejor experiencia del usuario y conservar la energía de retransmisión, considera implementar una caché pequeña en el dispositivo Wear OS para almacenar algunos APKs.

En el caso de que el usuario pruebe otra cara de reloj, pero luego decida volver a la que eligió anteriormente, esta acción es casi instantánea.

Del mismo modo, se puede usar para el almacenamiento en caché previo de la cara de reloj del día o esquemas similares en los que se descargan caras de reloj mientras se carga el dispositivo Wear OS.

Cómo actualizar las caras de reloj incluidas

Tu app puede incluir un recurso de cara de reloj predeterminado, como se describió anteriormente. Es importante reconocer que, si bien esta cara de reloj se instala en el sistema cuando se instala tu app del mercado, no se actualiza si se incluye una versión más reciente con cualquier actualización de la app del mercado.

Para controlar esta situación, la app del mercado debe detectar la acción de transmisión MY_PACKAGE_REPLACED y verificar si es necesario actualizar cualquier cara de reloj empaquetada desde los recursos del paquete.

Cara de reloj predeterminada representativa

Una cara de reloj predeterminada es una excelente forma de ayudar a los usuarios a descubrir y usar tu mercado: la cara de reloj se instala cuando se instala el mercado, de modo que los usuarios puedan encontrarla en la galería de caras de reloj.

Ten en cuenta lo siguiente cuando trabajes con caras de reloj predeterminadas:

  • No uses removeWatchFace si el usuario elige desinstalar una cara de reloj de tu app de mercado. En su lugar, en este caso, vuelve a la cara de reloj predeterminada con updateWatchFace. Esto ayuda a los usuarios a encontrar tu cara de reloj y configurarla desde la galería.
  • Haz que la cara de reloj predeterminada sea simple y se reconozca de inmediato a través de tu logotipo y temas. Esto ayuda a los usuarios a encontrarla en la galería de caras de reloj.

  • Agrega un botón a la cara de reloj predeterminada para abrir la app de teléfono. Esto se puede lograr en dos etapas:

    1. Agrega un elemento Launch a la cara de reloj para iniciar un intent con la app para Wear OS, por ejemplo:

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

    2. En LaunchOnPhoneActivity, inicia la app de teléfono con RemoteActivityHelper.