Cómo crear un servicio para caras de reloj

Una cara de reloj es un servicio empaquetado en una app de Wear OS. Cuando un usuario selecciona una cara de reloj disponible, se muestra la cara de reloj y se invocan los métodos de devolución de llamada de servicio.

Cuando un usuario instala una app de Wear OS que tiene caras de reloj, las caras de reloj están disponibles en el reloj por medio del selector de caras de reloj. De manera alternativa, el usuario puede seleccionar una cara de reloj desde una aplicación complementaria en el teléfono vinculado.

En esta página, se describe cómo configurar un proyecto de Wear OS para incluir caras de reloj y cómo implementar un servicio de caras de reloj.

Cómo crear un proyecto de cara de reloj

A fin de crear un proyecto en Android Studio para tu cara de reloj, haz lo siguiente:

  1. Haz clic en File > New > New Project.
  2. En la ventana Create Android Project, acepta los valores predeterminados y haz clic en Next.
  3. En la ventana Target Android Devices, selecciona solo la opción Wear y, en la lista de versiones de SDK, selecciona la versión más reciente disponible. Haz clic en Next.
  4. En la ventana Add an Activity to Wear, selecciona Watch Face y haz clic en Next.
  5. En la ventana Configure Activity, acepta los valores predeterminados y haga clic en Finish.

Android Studio crea un proyecto con un módulo de app para tu servicio de caras de reloj. Para obtener más información sobre los proyectos en Android Studio, consulta Cómo crear un proyecto.

Dependencias

La Biblioteca de compatibilidad con wearables proporciona las clases necesarias que extiendes para crear implementaciones de cara de reloj. Se requieren las bibliotecas cliente de los Servicios de Google Play (play-services y play-services-wearable) para sincronizar elementos de datos entre el dispositivo complementario y el wearable con la API de nivel de datos de wearable.

Android Studio agrega de manera automática las entradas necesarias en tus archivos build.gradle cuando creas el proyecto en las instrucciones anteriores.

Referencia de la API de la biblioteca de compatibilidad de wearables

En la documentación de referencia, se proporciona información detallada sobre las clases que usas para implementar caras de reloj. Consulta la documentación de referencia de la API de la Biblioteca de compatibilidad de wearables.

Nota: Recomendamos usar Android Studio para el desarrollo de Wear OS, ya que proporciona elementos prácticos de configuración de proyectos, inclusión de bibliotecas y empaquetado.

Cómo declarar permisos

Una cara de reloj requiere el permiso WAKE_LOCK. Agrega el siguiente permiso a los archivos de manifiesto de la app de Wear OS (app para wearables) y la app para dispositivos móviles (teléfono) en el elemento manifest:

    <manifest ...>
        <uses-permission
            android:name="android.permission.WAKE_LOCK" />

        <!-- Required for complications to receive complication data and open the provider chooser. -->
        <uses-permission
            android:name="com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA"/>
        ...
    </manifest>
    

Precaución: La app para dispositivos portátiles debe incluir todos los permisos declarados en la app para wearables.

Cómo implementar el servicio y los métodos de devolución de llamada

Las caras de reloj en Wear OS se implementan como servicios. Cuando una cara de reloj está activa, el sistema invoca los métodos en su servicio cuando cambia la hora o cuando ocurre un evento importante (como pasar al modo ambiente o recibir una notificación nueva). La implementación del servicio luego dibuja la cara de reloj en la pantalla usando la hora actualizada y cualquier otro dato relevante.

Para implementar una cara de reloj, extiende las clases CanvasWatchFaceService y CanvasWatchFaceService.Engine y, a continuación, anula los métodos de devolución de llamada de la clase CanvasWatchFaceService.Engine. Estas clases están incluidas en la biblioteca de compatibilidad de wearables.

En el siguiente fragmento de código, se describen los métodos clave que debes implementar:

Kotlin

    class AnalogWatchFaceService : CanvasWatchFaceService() {

        override fun onCreateEngine(): Engine {
            /* provide your watch face implementation */
            return Engine()
        }

        /* implement service callback methods */
        inner class Engine : CanvasWatchFaceService.Engine() {

            override fun onCreate(holder: SurfaceHolder) {
                super.onCreate(holder)
                /* initialize your watch face */
            }

            override fun onPropertiesChanged(properties: Bundle?) {
                super.onPropertiesChanged(properties)
                /* get device features (burn-in, low-bit ambient) */
            }

            override fun onTimeTick() {
                super.onTimeTick()
                /* the time changed */
            }

            override fun onAmbientModeChanged(inAmbientMode: Boolean) {
                super.onAmbientModeChanged(inAmbientMode)
                /* the wearable switched between modes */
            }

            override fun onDraw(canvas: Canvas, bounds: Rect) {
                /* draw your watch face */
            }

            override fun onVisibilityChanged(visible: Boolean) {
                super.onVisibilityChanged(visible)
                /* the watch face became visible or invisible */
            }
        }
    }
    

Java

    public class AnalogWatchFaceService extends CanvasWatchFaceService {

        @Override
        public Engine onCreateEngine() {
            /* provide your watch face implementation */
            return new Engine();
        }

        /* implement service callback methods */
        private class Engine extends CanvasWatchFaceService.Engine {

            @Override
            public void onCreate(SurfaceHolder holder) {
                super.onCreate(holder);
                /* initialize your watch face */
            }

            @Override
            public void onPropertiesChanged(Bundle properties) {
                super.onPropertiesChanged(properties);
                /* get device features (burn-in, low-bit ambient) */
            }

            @Override
            public void onTimeTick() {
                super.onTimeTick();
                /* the time changed */
            }

            @Override
            public void onAmbientModeChanged(boolean inAmbientMode) {
                super.onAmbientModeChanged(inAmbientMode);
                /* the wearable switched between modes */
            }

            @Override
            public void onDraw(Canvas canvas, Rect bounds) {
                /* draw your watch face */
            }

            @Override
            public void onVisibilityChanged(boolean visible) {
                super.onVisibilityChanged(visible);
                /* the watch face became visible or invisible */
            }
        }
    }
    

La clase CanvasWatchFaceService proporciona un mecanismo de invalidación similar al método View.invalidate(). Puedes llamar al método invalidate() durante la implementación cuando quieras que el sistema vuelva a dibujar la cara de reloj. Solo puedes usar el método invalidate() en el procesamiento principal de la IU. Para invalidar el lienzo desde otro subproceso, llama al método postInvalidate().

Para obtener más información sobre la implementación de los métodos en la clase CanvasWatchFaceService.Engine, consulta Cómo dibujar caras de reloj.

Cómo registrar el servicio de caras de reloj

Después de implementar el servicio de caras de reloj, registra la implementación en el archivo de manifiesto de la app para wearables. Cuando los usuarios instalan esta app, el sistema utiliza la información sobre el servicio para hacer que la cara de reloj esté disponible en la aplicación complementaria de Wear OS y en el selector de caras de reloj en el dispositivo wearable.

En el siguiente fragmento de código, se muestra cómo registrar una implementación de cara de reloj en el elemento application:

    <service
        android:name=".AnalogWatchFaceService"
        android:label="@string/analog_name"
        android:permission="android.permission.BIND_WALLPAPER" >
        <meta-data
            android:name="android.service.wallpaper"
            android:resource="@xml/watch_face" />
        <meta-data
            android:name="com.google.android.wearable.watchface.preview"
            android:resource="@drawable/preview_analog" />
        <meta-data
            android:name="com.google.android.wearable.watchface.preview_circular"
            android:resource="@drawable/preview_analog_circular" />
        <intent-filter>
            <action android:name="android.service.wallpaper.WallpaperService" />
            <category
                android:name=
                "com.google.android.wearable.watchface.category.WATCH_FACE" />
        </intent-filter>
    </service>
    

La aplicación complementaria de Wear OS y el selector de caras de reloj en el dispositivo wearable usan la imagen de vista previa definida por la entrada de metadatos com.google.android.wearable.watchface.preview para presentar a los usuarios todas las caras de reloj instaladas en el dispositivo. Para obtener este elemento de diseño, ejecuta la cara de reloj en tu dispositivo Wear OS o en una instancia de emulador y toma una captura de pantalla. En los dispositivos Wear OS con pantallas hdpi, la imagen de vista previa suele tener un tamaño de 320 × 320 píxeles.

Las caras de reloj que se ven muy diferentes en los dispositivos redondos pueden proporcionar imágenes de vista previa redondas y cuadradas. Para especificar una imagen de vista previa redonda, usa la entrada de metadatos com.google.android.wearable.watchface.preview_circular. Si la cara de reloj incluye ambas imágenes de vista previa, la aplicación complementaria y el selector de caras de reloj en el wearable muestran la adecuada según la forma del reloj. Si no se incluye una imagen de vista previa redonda, la imagen de vista previa cuadrada se utiliza para dispositivos tanto cuadrados como redondos. Para dispositivos redondos, una imagen de vista previa cuadrada se recorta con una forma circular.

La entrada de metadatos android.service.wallpaper especifica el archivo de recursos watch_face.xml, que contiene un elemento wallpaper:

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

Tu app para wearable puede incluir más de una cara de reloj. Debes agregar una entrada de servicio al archivo de manifiesto de la app para wearable para cada una de las implementaciones de la cara de reloj.