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 de 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 para o desenvolvimento 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 a dispositivos retangulares

Por padrão, os mostradores de relógio em dispositivos retangulares são executados no modo de emulação quadrada. Assim, há suporte a mostradores de relógio criados para dispositivos circulares e quadrados. Se você quiser oferecer suporte total a dispositivos retangulares, substitua esse comportamento criando uma tag meta-data no service do mostrador do relógio do seu manifest e definindo android.service.wallpaper.square_mode como false, conforme mostrado neste exemplo de código:

<manifest ...>
    <application ...>
        <service
            android:name=".MyWatchFace"
            android:label="My Watch Face"
            android:permission="android.permission.BIND_WALLPAPER">
            ...
            <meta-data
                android:name="android.service.wallpaper.square_mode"
                android:value="false" />
            ...
        </service>
    ...
    </application>
    ...
</manifest>

Implementar o serviço e os 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:

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

}

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

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