Criar um serviço para mostradores de relógio

Um mostrador do relógio é um serviço empacotado em um app para Wear OS. Quando o usuário seleciona uma opção disponível, o mostrador do relógio aparece e os métodos de callback de serviço são invocados.

Quando o usuário instala um app para Wear OS que possui mostradores de relógio, eles ficam disponíveis no seletor do relógio. Opcionalmente, o usuário pode selecionar um mostrador do relógio de um app complementar no smartphone pareado.

Esta página descreve como configurar um projeto do Wear OS para incluir mostradores de relógio e como implementar um serviço de mostrador do relógio.

Criar um projeto de mostrador do relógio

Observação: recomendamos o uso do Android Studio ao desenvolver para Wear OS, porque ele oferece configuração de projetos, inclusão de bibliotecas e facilidades no empacotamento.

Conclua as etapas abaixo para criar um projeto no Android Studio para o mostrador do relógio:

  1. Clique em Studio > New > New project.
  2. Na janela Select a project template, selecione a guia Wear. Em seguida, selecione Watch Face na lista de opções e clique em Next.
  3. Na janela Configure your project, aceite os valores padrão e clique em Finish.

O Android Studio cria um projeto com um módulo app para o serviço de mostrador do relógio.

Dependências

O Android Studio adiciona automaticamente as entradas necessárias nos arquivos build.gradle. A biblioteca de mostradores de relógio AndroidX está incluída nas dependências. Consulte o exemplo de código no GitHub para conferir detalhes sobre essa biblioteca.

Referência da API da Biblioteca de Suporte Wearable

A documentação de referência traz informações detalhadas sobre as classes que você usa para implementar mostradores de relógio. Navegue pela documentação de referência da API da Biblioteca de Suporte para Wearables.

Declarar permissões

O mostrador do relógio requer a permissão WAKE_LOCK. Adicione a permissão abaixo aos arquivos de manifesto do app para Wear OS e do app para smartphones no 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>

Suporte à inicialização direta

A tela do relógio precisa ficar disponível antes do desbloqueio do usuário. Para isso, siga as orientações da Inicialização direta:

  1. Defina o atributo android:directBootAware como true para o serviço no manifesto.
  2. O mostrador do relógio precisa armazenar informações no armazenamento criptografado do dispositivo.

Implementar o serviço e métodos de callback

Os mostradores de relógio no Wear OS são implementados como WatchFaceService. Para implementar um WatchFaceService, é necessário criar três objetos: um UserStyleSchema, um ComplicationSlotsManager e um WatchFace.

Esses três objetos são especificados substituindo três métodos abstratos do WatchFaceService, mostrados no exemplo a seguir:

Kotlin

class CustomWatchFaceService : WatchFaceService() {

    /**
     * The specification of settings the watch face supports.
     * This is similar to a database schema.
     */
    override fun createUserStyleSchema(): UserStyleSchema = // ...

    /**
     * The complication slot configuration for the watchface.
     */
    override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager = // ...

    /**
     * The watch face itself, which includes the renderer for drawing.
     */
    override suspend fun createWatchFace(
        surfaceHolder: SurfaceHolder,
        watchState: WatchState,
        complicationSlotsManager: ComplicationSlotsManager,
        currentUserStyleRepository: CurrentUserStyleRepository
    ): WatchFace = // ...

}

Registrar o serviço de mostrador do relógio

Depois de implementar o serviço de mostrador do relógio, registre a implementação no arquivo de manifesto do app para wearables. Quando os usuários instalam esse app, o sistema usa as informações sobre o serviço para disponibilizar o mostrador do relógio no app complementar do Wear OS e no seletor de mostradores no dispositivo wearable.

O snippet abaixo mostra como registrar uma implementação de mostrador do relógio no 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_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>

O app complementar do Wear OS by Google e o seletor de mostradores de relógio no dispositivo wearable usam a imagem da prévia definida pela entrada de metadados com.google.android.wearable.watchface.preview_circular ao apresentar aos usuários todos os mostradores instalados no dispositivo. Para gerar esse drawable, execute o mostrador do relógio no dispositivo Wear OS ou em uma instância do emulador e faça uma captura de tela. Em dispositivos Wear OS com telas HDPI, a imagem de prévia normalmente tem 320 x 320 pixels.

A entrada de metadados android.service.wallpaper especifica o arquivo de recursos watch_face.xml, que contém um elemento wallpaper, conforme mostrado neste exemplo:

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

Seu app para wearables pode conter mais de um mostrador de relógio. É necessário adicionar uma entrada de serviço ao arquivo de manifesto do app para wearable para cada implementação de mostrador do relógio.

Confira os seguintes recursos relacionados: