Configuração do formato do mostrador do relógio

Este guia inclui etapas sobre as ferramentas necessárias para configurar um mostrador de relógio usando o formato de mostrador do relógio, algumas sugestões sobre a estrutura do projeto e um guia detalhado para aplicar as ferramentas e criar essa estrutura.

Pré-requisitos

Para preparar seu ambiente de desenvolvimento para o uso do formato de mostrador do relógio, realize as seguintes etapas de configuração:

  1. Instale o SDK para o Android 14 (nível 34 da API) ou mais recente. Caso o mostrador do relógio não dependa de [recursos ou comportamentos específicos da versão 2][1], instale o SDK para o Android 13 (nível 33 da API).

    O SDK contém outras ferramentas necessárias, incluindo aapt2 e android.jar.

  2. Como alternativa, instale o [Android Studio][2], que também pode fornecer essas ferramentas.

Estrutura do projeto

Quando você cria um mostrador personalizado que usa o formato de mostrador do relógio, o Android App Bundle que inclui o arquivo de mostrador personalizado precisa ser completamente separado do Android App Bundle que contém a lógica do seu app para Wear OS. Algumas app stores, incluindo o Google Play, impedem que você faça upload de um Android App Bundle que inclua a lógica do Wear OS e um mostrador do relógio personalizado.

Criar pacote de mostrador do relógio

Para criar um Android App Bundle que tenha um arquivo de mostrador do relógio, siga as etapas mostradas nas seções a seguir.

Declarar o uso do formato de mostrador do relógio

No arquivo de manifesto do novo app (AndroidManifest.xml), adicione uma propriedade que indique o uso do Formato do mostrador do relógio. A menos que você queira restringir o acesso ao mostrador do relógio para dispositivos com o Wear OS 5 ou mais recente, crie dois APKs de mostrador do relógio diferentes, um com suporte à versão 2 e outro com suporte à versão 1. Saiba mais sobre como [configurar versões][3] do seu app.

APK compatível com a versão 2

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <application ...>
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

APK compatível com a versão 1

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <application ...>
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="1" />
    </application>
</manifest>

Declarar metadados do mostrador do relógio

No diretório de recursos res/xml do app, crie um novo arquivo chamado watch_face_info.xml. É nesse arquivo que você define os metadados do mostrador do relógio:

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>
    <!-- Only "Preview" is required. -->
    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

Os campos do arquivo representam os seguintes detalhes:

Preview
Faz referência ao drawable que contém uma imagem de visualização do mostrador do relógio.
Category

Define a categoria do mostrador do relógio. Precisa ser uma string ou uma referência a uma string, como @string/ref_name. Cada fabricante de dispositivo pode definir o próprio conjunto de categorias de mostradores de relógio.

Valor padrão: empty_category_meta, que agrupa esse mostrador do relógio com outros mostradores de "categoria vazia" na parte inferior da visualização do seletor.

AvailableInRetail

Indica se o mostrador do relógio está disponível no [modo de demonstração na loja][4] do dispositivo. Precisa ser um valor booleano ou uma referência a um valor booleano, como @bool/watch_face_available_in_retail.

Valor padrão: false

MultipleInstancesAllowed

Indica se o mostrador do relógio pode ter vários favoritos. Precisa ser um valor booleano ou uma referência a um valor booleano, como @bool/watch_face_multiple_instances_allowed.

Valor padrão: false

Editable

Indica se o mostrador do relógio é editável, o que significa que ele tem uma configuração ou pelo menos uma [complicação][5] não fixa. Isso é usado para mostrar ou ocultar o botão Edit do mostrador do relógio na lista de favoritos.

Valor padrão: false

Declarar o nome do mostrador do relógio

No arquivo de manifesto do app (AndroidManifest.xml), defina o atributo android:label como o nome do mostrador do relógio:

<application android:label="@string/watch_face_name" >

Declarar suporte a formas do mostrador do relógio (opcional)

Essa etapa só será necessária se você quiser oferecer suporte a comportamentos diferentes para tamanhos distintos de mostradores de relógio. Você pode pular esta etapa se quiser que o mostrador do relógio seja dimensionado de acordo com o tamanho dele.

No diretório de recursos res/xml do app, declare o conjunto de formas do mostrador do relógio aceitas em watch_face_shapes.xml:

<WatchFaces>
    <!-- The default shape is "CIRCLE". -->
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

Declarar detalhes do mostrador do relógio

No diretório de recursos res/raw do app, crie arquivos correspondentes aos valores do atributo file usados ao [declarar suporte a formas do mostrador do relógio][6].

É aqui que você define a aparência e o comportamento do mostrador do relógio para cada formato. Se você não definiu um arquivo de formas, só precisa criar um arquivo, watchface.xml.

Usando o exemplo desta página, os arquivos XML brutos seriam:

  • res/raw/watchface.xml
  • res/raw/watchface_large_circle.xml
  • res/raw/watchface_rectangle.xml

O elemento raiz é sempre [WatchFace][7]:

<WatchFace width="450" height="450" shape="CIRCLE">
    <!-- Remainder of your Watch Face Format definition here. -->
    <!-- If this file defines a watch face for a circular device shape, place
         resources used in this file in the "/res/drawable-nodpi" directory. -->
    <!-- If this file defines a watch face for a rectangular or other
         non-circular shape, place resources ued in this file in the
         "/res/drawable-notround-nodpi" directory. -->
</WatchFace>

Identificar o editor do mostrador do relógio (opcional)

Como opção, declare uma string arbitrária no arquivo de manifesto do seu app para identificar o editor do mostrador do relógio ou o nome e a versão da ferramenta que você está usando:

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="{toolName}-{toolVersion}" />
</application>

Verificar a precisão e o desempenho do mostrador do relógio

Durante o desenvolvimento e antes de fazer upload no Google Play, use as [ferramentas de validação][9] para verificar se o mostrador do relógio não tem erros e se ele está em conformidade com as recomendações de uso da memória.

  • Saiba mais sobre [como otimizar o uso de memória][8] e [verificar o uso de memória][11] em preparação para a publicação.
  • Saiba mais sobre como usar o [validador XML][12] como parte do ciclo de desenvolvimento.

Criar seu pacote de apps para o mostrador do relógio

Para criar o Android App Bundle que contém o mostrador do relógio, use o sistema de build do Gradle. Saiba mais sobre como [criar um app usando o Gradle][13].

Isso é demonstrado nos [exemplos do GitHub][14].