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

Watch Face Push permite que tu app administre caras de reloj en un dispositivo Wear OS. Esto incluye agregar, actualizar y quitar caras de reloj, así como establecer la cara de reloj activa. Configura tu app para Wear OS para usar la API de Watch Face Push.

Configuración

Incluye las dependencias necesarias:

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

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 = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager proporciona acceso a todos los métodos para interactuar con Watch Face Push.

Trabaja con ranuras

Un concepto clave cuando se trabaja con Watch Face Push son las ranuras. Las ranuras son una forma de hacer referencia a las caras de reloj instaladas que pertenecen a tu aplicación. El sistema establece una cantidad máxima de ranuras que puede tener un mercado. Con Wear OS 6, el límite es 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 la 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 la ranura está disponible o si agregar otra cara de reloj requiere reemplazar la existente. En la lista, también se brindan detalles sobre la cara de reloj instalada. Por ejemplo, para verificar si está instalado un paquete de cara de reloj determinado, 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 determina la respuesta de 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.
}

Nota: No almacenes valores de slotId ni los trates como persistentes. El estado podría cambiar fuera de tu aplicación. Por ejemplo, un usuario podría desinstalar la cara de reloj a través de la IU del sistema. Siempre obtén el estado actual inmediatamente antes de cualquier operación basada en ranuras.

Actualiza una cara de reloj

Actualizar una cara de reloj te permite reemplazar el contenido de una ranura determinada por un paquete nuevo. Esto podría implicar 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.
}

Nota: Considera si tu app debería llamar a removeWatchFace. En cambio, cuando el usuario presione para desinstalar una cara de reloj a través de tu app de mercado, es posible que quieras reemplazarla por una cara de reloj predeterminada.

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

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

Es importante determinar si tu mercado tiene establecida la cara de reloj activa para garantizar que el usuario tenga una experiencia fluida: Si el mercado ya tiene establecida la cara de reloj activa, si el usuario desea elegir otra cara de reloj, solo necesita reemplazar la actual a través de la app del mercado para que esto surta efecto. Sin embargo, si el mercado no tiene establecida la carátula del reloj activa, la app para teléfonos debe ofrecerle más orientación al usuario. Consulta la sección sobre la app de Teléfono para obtener más detalles sobre cómo controlar esta experiencia del usuario.

Para determinar si el mercado tiene establecida la cara de reloj activa, usa la siguiente lógica:

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

Advertencia: Cuando llames a updateWatchFace(), no llames a isWatchFaceActive() inmediatamente después, ya que esto puede generar resultados inesperados. El cambio de cara de reloj puede tardar un poco en completarse.

En cambio, primero determina si la app que llama tiene una referencia a la cara de reloj activa, como se muestra en el fragmento anterior, y luego llama a updateWatchFace(). Si updateWatchFace() se completa correctamente, puedes suponer que tu app aún tiene el control de la cara de reloj activa.

Proporciona una cara de reloj predeterminada

La función Watch Face Push ofrece la posibilidad de instalar una cara de reloj predeterminada cuando se instala tu app de mercado. Esto no establece, por sí solo, esa cara de reloj predeterminada como activa (consulta cómo establecer la cara de reloj activa), pero garantizará 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" />
   

Nota: Un patrón de compilación típico incluye la compilación de tu default_watchface.apk como parte de la compilación general de la app como un paso previo a la compilación. Puedes usarlo para completar el valor del manifiesto del token de validación haciendo que el proceso de compilación de la cara de reloj predeterminada genere un archivo XML de recursos de Android adicional y que incluya esa ruta de recursos como una ruta de recursos adicional dentro de tu app principal. Este enfoque es más simple que intentar manipular el archivo de manifiesto durante el proceso de compilación.

Cómo establecer la cara de reloj activa

El envío de caras de reloj proporciona los medios para que la app de 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 cara de reloj se realiza a través de una llamada a updateWatchFace para reemplazar el contenido de la ranura de la cara de reloj por otra cara de reloj.

Establecer la cara de reloj activa es un proceso de dos etapas:

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

Adquiere permisos para establecer la cara de reloj activa

El permiso requerido 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 solicitarlo al usuario cuando se ejecute (considera la biblioteca de Accompanist para ayudarte con esto).

Nota: Este permiso tiene un recuento máximo de rechazos de 1: Si el usuario rechaza la solicitud, no se podrá volver a realizar. En ese caso, la app debe dirigir al usuario a la configuración para que ajuste el permiso de forma manual.

Establecer la cara de reloj como activa

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

watchFacePushManager.setWatchFaceAsActive(slotId)

Nota: La carátula activa solo se puede configurar de esta manera una vez. Si el usuario cambia a una cara de reloj de otro desarrollador, llamar a esta API para restablecer tu cara de reloj como la cara de reloj activa arroja una excepción.

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

Cómo leer metadatos adicionales del APK de la cara de reloj

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

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

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

Sin embargo, esta cara de reloj podría venir en cuatro APKs 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 XML del formato de cara de reloj.

Esta pequeña 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" />

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

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

Nota: En el ejemplo anterior, se debió proporcionar el espacio de nombres para la propiedad porque se declaró none en la propiedad. Si la propiedad incluye un punto (.), esto no es necesario, por lo que se puede recuperar una propiedad llamada abc.def con getMetaDataValues("abc.def").

Consideraciones

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

Energía

Un factor 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 Marketplace, 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:
   • Cómo minimizar la activación de la app desde la app de Teléfono
   • Cómo minimizar la ejecución de trabajos de WorkManager
2. Programa los informes de Analytics para cuando el reloj se esté cargando:
   1. Si deseas informar estadísticas de uso desde la app para Wear OS o cualquier otra métrica, usa WorkManager con la restricción requiresCharging.
3. Programa las actualizaciones para cuando el reloj se esté cargando y usa Wi-Fi:
   1. Es posible que quieras verificar las versiones de las caras de reloj instaladas y actualizarlas automáticamente. Nuevamente, usa la restricción requiresCharging y el tipo de red UNMETERED para requiresNetworkType.
   2. Cuando el dispositivo se está cargando, es probable que tenga acceso a Wi-Fi. Solicita Wi-Fi para descargar rápidamente los APKs actualizados y libera la red cuando termines.
   3. Esta misma orientación se aplica a los casos en los que el mercado puede ofrecer una cara de reloj del día. Descárgala previamente mientras el reloj se carga.
4. No programes trabajos para verificar la cara de reloj activa:
   1. Comprobar periódicamente si el mercado aún tiene la cara de reloj activa y cuál es genera un consumo de batería. Evita este enfoque.
5. No usar 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 con la app para el reloj a través de setLocalOnly.

Almacenamiento en caché

En el ejemplo canónico del mercado, 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 había elegido anteriormente, esta acción será casi instantánea.

Del mismo modo, se puede usar para el almacenamiento previo en caché 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.

Actualiza 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 de mercado, la cara de reloj no se actualiza si se incluye una versión más reciente con alguna actualización de tu app de mercado.

Para controlar esta situación, tu app de mercado debe detectar la acción de transmisión MY_PACKAGE_REPLACED y verificar si es necesario actualizar alguna carátula de reloj incluida en los recursos del paquete.

Cara de reloj predeterminada representativa

Una cara de reloj predeterminada es una excelente manera de ayudar a los usuarios a descubrir y usar tu mercado: la cara de reloj se instala cuando se instala tu mercado, por lo que los usuarios pueden encontrarla en la galería de caras de reloj.

A continuación, se incluyen algunas consideraciones para trabajar con caras de reloj predeterminadas:

• No uses removeWatchFace si el usuario elige desinstalar una cara de reloj de tu app de mercado. En cambio, en este caso, revierte la cara de reloj a la cara de reloj predeterminada con updateWatchFace. Esto ayuda a los usuarios a encontrar tu cara de reloj y establecerla desde la galería.
• Haz que la cara de reloj predeterminada sea simple y se reconozca al instante con tu logotipo y tu tema. 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 del reloj para iniciar un intent con la app de Wear OS, por ejemplo:

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

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