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

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

Configurar

Inclua as dependências necessárias:

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

Adicione o seguinte ao seu 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 da instância do gerenciador

Receba uma instância de WatchFacePushManager:

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager fornece acesso a todos os métodos para interagir com o envio por push de mostradores do relógio.

Trabalhar com slots

Um conceito importante ao trabalhar com o envio de mostradores de relógio é o de slots. Os slots são uma forma de endereçar mostradores de relógio instalados que pertencem ao seu aplicativo. O sistema define um número máximo de slots que um marketplace pode ter. No Wear OS 6, o limite é 1.

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

Listar 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 fornece 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() deverá 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.
}

Observação: não armazene valores slotId nem os trate como persistentes. O estado pode mudar fora do aplicativo. Por exemplo, um usuário pode desinstalar o mostrador do relógio pela interface do sistema. Sempre obtenha o estado atual imediatamente antes de qualquer operação baseada em slot.

Atualizar um mostrador do relógio

Ao atualizar um mostrador de relógio, você pode substituir o conteúdo de um determinado slot por um novo pacote. Isso pode ser o upgrade do mesmo mostrador do relógio para uma versão mais recente ou a substituição completa 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.
}

Observação: considere se o app precisa chamar removeWatchFace. Em vez disso, quando o usuário tocar para desinstalar um mostrador do relógio pelo app do marketplace, você pode querer substituí-lo por um mostrador padrão.

Isso garante que o mostrador do relógio possa sempre ser encontrado no seletor de mostradores do sistema, que seu logotipo apareça em destaque e que até mesmo um botão para iniciar o app do Marketplace no smartphone seja exibido.

Verificar se o mostrador do relógio está ativo

É importante determinar se o mostrador do relógio ativo está definido no marketplace para garantir uma experiência tranquila ao usuário. Se o mostrador ativo já estiver definido no marketplace, o usuário só precisará substituir o atual pelo app do marketplace para que a mudança seja aplicada. No entanto, se o marketplace não tiver o mostrador do relógio ativo definido, o app para smartphone precisará oferecer mais orientação ao usuário. Consulte a seção sobre o app Telefone para mais detalhes sobre como lidar com essa experiência do usuário.

Para determinar se o mercado tem o mostrador do relógio ativo definido, use a seguinte lógica:

val hasActiveWatchFace = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

Aviso: ao chamar updateWatchFace(), não chame isWatchFaceActive() imediatamente depois, porque isso pode levar a resultados inesperados. Pode levar algum tempo para a troca do mostrador do relógio ser concluída.

Em vez disso, primeiro determine se o app de chamada tem uma referência ao mostrador do relógio ativo, conforme mostrado no snippet anterior, e depois chame updateWatchFace(). Se updateWatchFace() for concluído com êxito, você poderá presumir que o app ainda tem controle do mostrador de relógio ativo.

Fornecer um mostrador de relógio padrão

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

Para usar esse recurso:

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

2. Adicione a seguinte entrada ao seu AndroidManifest.xml

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

Observação: um padrão de build típico inclui a criação do default_watchface.apk como parte do build geral do app em uma etapa de pré-build. Você pode usar isso para preencher o valor do manifesto do token de validação fazendo com que o processo de build do mostrador do relógio padrão gere um arquivo XML de recursos do Android adicional e inclua esse caminho de recursos como um caminho adicional no app principal. Essa abordagem é mais simples do que tentar manipular o arquivo de manifesto durante o processo de build.

Definir o mostrador do relógio ativo

O Watch Face Push oferece os meios para o app da loja 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 por outro.

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

Observação: essa permissão tem uma contagem máxima de rejeição de 1: se o usuário negar a solicitação, ela não poderá ser feita novamente. Nesse caso, o app precisa direcionar o usuário às configurações para ajustar manualmente a permissão.

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 deve estar ativo:

watchFacePushManager.setWatchFaceAsActive(slotId)

Observação: o mostrador do relógio ativo só pode ser definido dessa forma uma vez. Se o usuário mudar para um mostrador de relógio de outro desenvolvedor, chamar essa API para definir o mostrador ativo de volta para o seu vai gerar uma exceção.

Depois que esse meio 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 oferece os meios para obter mais informações que podem ser declaradas no mostrador do relógio.

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

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

Mas esse mostrador do relógio pode vir 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" />

Usar uma propriedade personalizada permite que o app determine qual dessas variantes está instalada:

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

Observação: no exemplo anterior, o namespace precisava ser fornecido para a propriedade porque none foi declarado nela. Se a propriedade incluir um ponto (.), isso não será necessário. Portanto, uma propriedade chamada abc.def poderá ser recuperada usando getMetaDataValues("abc.def").

Considerações

Ao implementar o envio por push de mostradores de relógio no seu app, é importante se concentrar no consumo de energia, no armazenamento em cache, na atualização de mostradores agrupados e no fornecimento de um mostrador padrão representativo.

Energia

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

1. Seu app deve ser executado o mínimo e com a menor frequência possível, a menos que o usuário esteja interagindo diretamente com ele. Isso inclui:
   • Minimizar a ativação do app no app Telefone
   • Minimizar a execução de jobs do WorkManager
2. Programe os relatórios de análise para quando o relógio estiver carregando:
   1. Se você quiser denunciar estatísticas de uso do app Wear OS ou outras métricas, use o WorkManager com a restrição requiresCharging.
3. Agendar atualizações para quando o relógio estiver carregando e usando Wi-Fi:
   1. Confira as versões dos mostradores instalados e atualize-os automaticamente. De novo, use a restrição requiresCharging e o tipo de rede UNMETERED para requiresNetworkType.
   2. Quando está carregando, o dispositivo provavelmente tem acesso ao Wi-Fi. Peça Wi-Fi para baixar rapidamente os APKs atualizados e libere a rede quando terminar.
   3. Essa mesma orientação se aplica a quando o marketplace oferece um mostrador do relógio 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 mercado ainda tem o mostrador do relógio ativo e qual é o mostrador consome a bateria. Evite essa abordagem.
5. Não usar 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 eles não fazem ponte com o app de relógio usando setLocalOnly.

Armazenamento em cache

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

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

Se o usuário tentar outro mostrador de relógio, mas decidir voltar ao que tinha escolhido antes, essa ação será quase instantânea.

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

Atualizar mostradores de relógio agrupados

Seu app pode incluir um recurso de mostrador de relógio padrão, conforme descrito anteriormente. É importante reconhecer que, embora a 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 em alguma 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 a necessidade de atualizar qualquer mostrador de relógio agrupado dos recursos do pacote.

Mostrador padrão representativo

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

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

• Não use removeWatchFace se o usuário escolher desinstalar um mostrador do relógio do app do marketplace. Em vez disso, nesse caso, reverta o mostrador do relógio 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 instantaneamente reconhecível 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 Telefone. Isso pode ser feito em duas etapas:

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

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

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