Configurar o app Wear OS para push de mostrador do relógio

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O Push de mostrador do relógio permite que seu app gerencie mostradores de relógio em um dispositivo Wear OS. Isso inclui adicionar, atualizar e remover mostradores de relógio, além de definir o mostrador ativo. Configure o app Wear OS para usar a API Push do mostrador do relógio.

Configurar

Inclua as dependências necessárias:

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

Adicione o seguinte ao 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>

Receber uma referência à instância do gerenciador

Receba uma instância de WatchFacePushManager:

val manager = WatchFacePushManager(context)

WatchFacePushManager fornece acesso a todos os métodos de interação com o push do mostrador do relógio.

Trabalhar com slots

Um conceito importante ao trabalhar com o push de mostrador do relógio são os slots. Os slots são uma forma de direcionar mostradores de relógio instalados que pertencem ao seu app. O sistema define um número máximo de slots que um marketplace pode ter. Com o Wear OS 6, o limite é 1.

Ao atualizar ou remover um mostrador do relógio, slotId é usado para identificar o mostrador do relógio em que a operação será realizada.

Mostrar mostradores de relógio

Para listar o conjunto de mostradores do relógio instalados, use listWatchFaces():

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

Isso permite determinar se o slot está disponível ou se adicionar outro mostrador do relógio exige a substituição do atual. A lista também mostra detalhes sobre o mostrador do relógio instalado. Por exemplo, para verificar se um determinado pacote de mostrador do relógio está instalado:

suspend fun isInstalled(packageName: String) = watchFacePush.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }

Adicionar um mostrador do relógio

Se houver slots disponíveis, conforme determinado pela resposta listWatchFaces, o método addWatchFace() precisará ser usado:

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

Atualizar um mostrador do relógio

A atualização de um mostrador de relógio permite substituir o conteúdo de um determinado slot por um novo pacote. Isso pode ser um upgrade do mesmo mostrador do relógio para uma versão mais recente ou a substituição completa do mostrador do relógio por outro.

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

Remover um mostrador do relógio

Para remover um mostrador do relógio:

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

Isso vai garantir que a tela do relógio possa ser sempre encontrada no seletor de telas do sistema, que seu logotipo possa aparecer em destaque e que seja possível até mesmo incluir um botão para iniciar o app Marketplace no smartphone.

Verificar se o mostrador do relógio está ativo

Determinar se o marketplace tem o mostrador do relógio ativo é importante para garantir que o usuário tenha uma experiência tranquila: se o marketplace já tiver o mostrador do relógio ativo, se o usuário quiser escolher outro mostrador ele só vai precisar substituir o atual pelo app do marketplace para que isso entre em vigor. No entanto, se o marketplace não tiver o mostrador de relógio ativo definido, o app para smartphone precisará oferecer mais orientações ao usuário. Consulte a seção sobre o app para smartphone para saber mais sobre como processar essa experiência do usuário.

Para determinar se o marketplace tem o mostrador do relógio ativo definido:

Fornecer um mostrador de relógio padrão

O Push de mostrador do relógio oferece a capacidade de instalar um mostrador de relógio padrão quando o app do marketplace é instalado. Isso não define o mostrador padrão como ativo (consulte a definição do mostrador do relógio ativo), mas garante que o mostrador do relógio esteja disponível no seletor de mostrador do relógio do sistema.

Para usar esse recurso:

1. No build do app para Wear OS, inclua o mostrador do relógio padrão no caminho: assets/default_watchface.apk

2. Adicione a seguinte entrada ao AndroidManifest.xml

   <application ...>
   <meta-data
       android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
       android:value="@string/default_wf_token" />
   

Definir o mostrador do relógio ativo

O push de mostrador do relógio fornece os meios para o app do marketplace definir o mostrador do relógio ativo.

Isso significa especificamente que o app pode definir o mostrador do relógio ativo como um pertencente ao marketplace no caso em que o mostrador do relógio ativo atual não pertence ao marketplace. No caso em que o marketplace já tem o mostrador do relógio ativo, a mudança para outro mostrador é feita por uma chamada para updateWatchFace para substituir o conteúdo do slot do mostrador do relógio por outro.

A configuração do mostrador do relógio ativo é um processo de duas etapas:

1. Adquira a permissão do Android necessária para definir o mostrador do relógio ativo.
2. Chame o método setWatchFaceAsActive.

Adquirir permissões para definir o mostrador do relógio ativo

A permissão necessária é SET_PUSHED_WATCH_FACE_AS_ACTIVE, que precisa ser adicionada ao manifesto:

<?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 essa é uma permissão de execução, seu app precisa solicitar essa permissão ao usuário quando ele é executado. Considere usar a biblioteca Accompanist para ajudar com isso.

Definir o mostrador do relógio como ativo

Depois que a permissão for concedida, chame setWatchFaceAsActive no ID do slot do mostrador do relógio que precisa estar ativo:

watchFacePushManager.setWatchFaceAsActive(slotId)

Depois que esse recurso for usado, o app para smartphone vai oferecer orientações sobre como definir manualmente o mostrador do relógio ativo.

Ler outros metadados do APK do mostrador do relógio

O objeto WatchFaceSlot também fornece meios para conseguir mais informações que você pode declarar no mostrador do relógio.

Isso pode ser útil, principalmente em cenários em que você tem variantes menores do mesmo mostrador do relógio. Por exemplo, você pode ter um mostrador do relógio definido:

• Nome do pacote: com.myapp.watchfacepush.mywatchface
• Versão do pacote: 1.0.0

No entanto, esse mostrador do relógio pode ser fornecido como quatro APKs diferentes, em que todos são quase exatamente iguais, mas com cores padrão diferentes: vermelho, amarelo, verde e azul, definidos em um ColorConfiguration no XML do formato do mostrador do relógio.

Essa pequena variação é refletida em cada um dos quatro APKs:

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
        android:name="default_color"
        android:value="red" />

O uso de uma propriedade personalizada permite que o app determine qual dessas variantes está instalada:

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

Considerações

Considerações importantes ao implementar o push de mostrador do relógio no app incluem o foco no consumo de energia, o armazenamento em cache, a atualização de mostradores de relógio agrupados e a disponibilização de um mostrador de relógio padrão representativo.

Energia

Uma consideração importante para qualquer app executado no Wear OS é o consumo de energia. Para o componente Wear OS do app do marketplace:

1. O app precisa ser executado o mínimo possível e com pouca frequência (a menos que o usuário interaja diretamente com ele). Isso inclui:
   • Minimizar a ativação do app pelo app Telefone
   • Como minimizar a execução de jobs do WorkManager
2. Programe qualquer relatório de análise para quando o relógio estiver carregando:
   1. Se você quiser informar estatísticas de uso do app Wear OS ou de qualquer outra métrica, use o WorkManager com a restrição requiresCharging.
3. Programe atualizações para quando o relógio estiver carregando e use o Wi-Fi:
   1. Verifique as versões dos mostradores do relógio instalados e atualize-as automaticamente. Novamente, use a restrição requiresCharging e o tipo de rede UNMETERED para requiresNetworkType.
   2. Quando estiver carregando, o dispositivo provavelmente terá acesso ao Wi-Fi. Solicite Wi-Fi para fazer o download rápido dos APKs atualizados e libere a rede quando terminar.
   3. Essa mesma orientação se aplica quando o marketplace oferece um mostrador do dia. Faça o pré-download enquanto o relógio está carregando.
4. Não programe jobs para verificar o mostrador do relógio ativo:
   1. Verificar periodicamente se o marketplace ainda tem o mostrador do relógio ativo e qual mostrador do relógio ele é coloca um consumo na bateria. Evite essa abordagem.
5. Não use notificações no relógio:
   1. Se o app usar notificações, concentre-as no smartphone, em que a ação do usuário abre o app para continuar a jornada. Verifique se elas não são vinculadas ao app do relógio usando setLocalOnly.

Armazenamento em cache

No exemplo de mercado canônico, os mostradores do relógio são transferidos do smartphone para o relógio. Essa conexão geralmente é Bluetooth, que pode ser bastante lenta.

Para oferecer uma melhor experiência ao usuário e economizar energia de retransmissão, implemente um pequeno cache no dispositivo Wear OS para armazenar alguns APKs.

No caso em que o usuário tenta outro mostrador do relógio, mas depois decide voltar para o mostrador escolhido anteriormente, essa ação é quase instantânea.

Da mesma forma, isso pode ser usado para pré-cachear o mostrador do relógio do dia ou esquemas semelhantes em que os mostradores do relógio são transferidos por download enquanto o dispositivo Wear OS está carregando.

Atualizar mostradores de relógio agrupados

O app pode incluir um recurso de mostrador de relógio padrão, conforme descrito anteriormente. É importante reconhecer que, embora essa aparência do relógio seja instalada no sistema quando o app do marketplace é instalado, ela não é atualizada se uma versão mais recente for incluída com qualquer atualização do app do marketplace.

Para lidar com essa situação, o app do marketplace precisa detectar a ação de transmissão MY_PACKAGE_REPLACED e verificar se é necessário atualizar qualquer mostrador de relógio agrupado dos recursos do pacote.

Mostrador de relógio padrão representativo

Um mostrador do relógio padrão é uma ótima maneira de ajudar os usuários a descobrir e usar seu marketplace: o mostrador do relógio é instalado quando o marketplace é, para que os usuários possam encontrá-lo na galeria de mostradores do relógio.

Algumas considerações ao trabalhar com mostradores de relógio padrão:

• Não use removeWatchFace se o usuário decidir desinstalar um mostrador de relógio do app do marketplace. Nesse caso, reverta o mostrador para o padrão usando updateWatchFace. Isso ajuda os usuários a localizar e definir o mostrador do relógio na galeria.
• Deixe o mostrador de relógio padrão simples e reconhecível instantaneamente com seu logotipo e tema. Isso ajuda os usuários a encontrar o mostrador na galeria.

• Adicione um botão ao mostrador de relógio padrão para abrir o app do smartphone. Isso pode ser feito em duas etapas:

  1. Adicione um elemento Launch ao mostrador do relógio para iniciar uma intent usando o app para Wear OS, por exemplo:

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

  2. Em LaunchOnPhoneActivity, inicie o app Telefone usando RemoteActivityHelper.