Melhorar a compatibilidade de apps em dispositivos Wear OS

A API Wear Health Services (WHS) é um componente obrigatório para todos os dispositivos com Wear OS 3 e mais recentes, já que fornece uma plataforma de integração consistente para desenvolvedores de apps de saúde e fitness. Crie seu app para se ajustar corretamente a vários dispositivos e às diferentes capabilities oferecidas por eles, melhorando a compatibilidade e evitando problemas na experiência do usuário. Para fazer isso, declare dependências somente para os clientes que seu app usa. Além disso, dê ao app a flexibilidade de mostrar ou remover métricas avançadas opcionais com base na disponibilidade delas.

Sensores diferentes geram dados em frequências distintas que variam por dispositivo com base no hardware e na plataforma do sensor. Por exemplo, um dispositivo pode retornar a frequência cardíaca em um carimbo de data/hora e o local em outro. Crie apps que possam receber fluxos de dados independentes em carimbos de data/hora diferentes ou sobrepostos.

Este guia descreve os comportamentos e os tipos de dados esperados que são compatíveis com vários clientes no Wear Health Services.

Cliente de exercícios

As seções abaixo descrevem os tipos de dados e os comportamentos esperados do ExerciseClient.

Comportamentos esperados

Para o ExerciseClient, alguns tipos de exercício dependem da disponibilidade de determinados tipos de dados. Por exemplo, exercícios em cadeira de rodas só vão estar disponíveis se o dispositivo oferecer suporte a eles. Ative e desative essas opções com base na disponibilidade em um determinado dispositivo.

A maioria dos tipos de dados de exercício é amostrada e entregue em intervalos de um segundo, com algumas exceções:

  • Em algumas situações, alguns tipos de dados de exercício são atualizados mais de uma vez por segundo. Por exemplo, quando o usuário está correndo, a contagem de passos é atualizada mais de uma vez por segundo.
  • Para alguns tipos de dados, uma atualização vai ser entregue somente se o valor atual for diferente do valor anterior.

A entrega de dados pode ser feita por streaming ou em lote. Os dados são transmitidos enquanto o processador do aplicativo está ativado, o que geralmente acontece quando a tela está ativada e é possível interagir com ela. Quando a tela é desligada ou entra no modo ambiente (ligada, mas não interativa), os dados são agrupados em lote para economizar energia. Os dados em lote são entregues ao aplicativo quando o smartwatch sai do modo ambiente e o processador do aplicativo é ativado novamente ou quando os buffers para lote estão cheios, o que varia de acordo com o dispositivo. A taxa de amostragem permanece a mesma enquanto o dispositivo está no modo ambiente para que os lotes entregues ainda tenham pontos de dados de alta frequência.

Os tipos de dados são derivados apenas dos dados gerados pelos sensores no smartwatch. Por exemplo, os dados de local vêm inteiramente do smartwatch, e não do smartphone.

Tipos de dados

A API ExerciseClient permite iniciar, pausar, retomar e interromper treinos de tipos diferentes. O WHS define um conjunto de tipos de dados disponibilizados para cada tipo de exercício. Isso economiza energia e simplifica a lógica do app, porque os sensores que não são necessários para um determinado exercício não são ativados. Por exemplo, ao iniciar uma corrida, os dados de local são fornecidos e rastreados apenas para corridas ao ar livre. Ao iniciar um exercício de ciclismo, os passos não são fornecidos ou monitorados. As próximas seções descrevem os tipos de dados com suporte do ExerciseClient.

Tipos garantidos de dados de exercício

Os tipos de dados de exercício abaixo estão disponíveis em todos os dispositivos.

  • Os tipos de dados de exemplo têm um tipo de dados _STATS correspondente que retorna valores mínimos, máximos e médios do exercício. Por exemplo, as estatísticas de PACE podem ser extraídas com o tipo de dados PACE_STATS.
  • Os tipos de dados de intervalo têm um tipo de dados _TOTAL correspondente que retorna o valor cumulativo do exercício. Por exemplo, as estatísticas de DISTANCE podem ser extraídas com o tipo de dados DISTANCE_TOTAL.
Métrica Dados esperados Observações sobre os comportamentos esperados
HEART_RATE_BPM Batimentos por minuto [Tipo de dados: Double] Todos os dispositivos medem a frequência cardíaca uma vez por segundo durante um exercício. Alguns dispositivos informam um valor de BPM a cada segundo. Alguns dispositivos só informam os BPM quando o valor muda. Não espere receber um valor de BPM a cada segundo em todos os dispositivos.
LOCATION Latitude e longitude [Tipo de dados: Double] Os dados de local são baseados apenas no GPS do smartwatch. Não espere que os dados de local sejam do provedor de localização combinada ou de outros serviços do Android. Cada ponto de dados também inclui um valor de precisão (também conhecido como erro de posição horizontal) e a disponibilidade.
STEPS [Tipo de dados: longo] A contagem de passos é um total somado ao longo da duração do exercício, não incluindo o tempo em que o exercício fica pausado.
DISTANCE Metros [Tipo de dados: Double] Calculada da localização baseada em GPS quando disponível, caso contrário, se baseia na contagem de passos. O valor final se refere ao total ao longo da duração do exercício, não incluindo o tempo em que o exercício fica pausado.
SPEED [metros / segundo] [Tipo de dados: Double] Retorna valores mínimos, máximos e médios. A duração deles é a duração do exercício, sem incluir o tempo em que ele fica pausado.
PACE [segundos / metro] [Tipo de dados: Double] O valor padrão vai ser 0 se a velocidade for 0. As médias consideram a duração do exercício, sem incluir o tempo em que o exercício fica pausado.
ELEVATION_GAIN Metros. [Tipo de dados: Double] Mudanças positivas na elevação. O total é informado durante o exercício, sem incluir o tempo de pausa.
TOTAL_CALORIES kCal [Tipo de dados: Double] Calorias ativas queimadas adicionadas à taxa metabólica basal (BMR, na sigla em inglês). As calorias emitidas aqui consideram a altura, o peso, a idade e o sexo do usuário, conforme especificado nas configurações do sistema. As calorias não consideram nenhum dado de perfil de usuário coletado no seu app. O total informado é maior que a duração do exercício, sem incluir o tempo em que o exercício ficou pausado.

Tipos opcionais de dados de exercício

Os tipos de dados listados abaixo estão disponíveis apenas em alguns dispositivos. Consulte a referência do Jetpack para uma lista completa de tipos de dados. Se um tipo de dados não estiver marcado na lista como "obrigatório/garantido", ele é opcional.

Confira os exemplos abaixo de tipos de dados opcionais. Esta não é uma lista completa:

Métrica Dados esperados Observações sobre os comportamentos esperados
ABSOLUTE_ELEVATION [Tipo de dados: Double]
ELEVATION_LOSS Metros [Tipo de dados: Double] Mudanças negativas na elevação. O valor é positivo. Por exemplo, uma perda de elevação de 1 m é retornada como 1, não -1.
STEPS_PER_MINUTE [Tipo de dados: longo]
WHEELCHAIR_PUSHES [Tipo de dados: longo] Nos exercícios com cadeira de rodas, são as vezes em que o usuário empurrou a cadeira.
REP_COUNT [Tipo de dados: longo]
SWIM_STROKE_COUNT [Tipo de dados: longo]
SWIM_LAP_COUNT [Tipo de dados: longo]

Tipos de dados por exercício

Diferentes tipos de dados são retornados para cada tipo de exercício. Os tipos de dados retornados são consistentes com as necessidades do exercício. Por exemplo, o tipo de exercício BIKING não retorna o tipo de dados STEPS. Use o método Capabilities durante a execução para determinar quais tipos de dados têm suporte no dispositivo do usuário.

No mínimo, todos os tipos de exercício retornam dados de frequência cardíaca e calorias. Outros exercícios podem oferecer suporte a outros tipos de dados, dependendo dos requisitos do exercício.

Confira alguns exemplos:

  • Exercícios como meditação ou pilates permitem relatar apenas a frequência cardíaca e as calorias.
  • Exercícios como basquete ou badminton oferecem suporte a dados de frequência cardíaca, calorias, distância e passos.
  • Exercícios como caminhada e corrida oferecem suporte a dados de frequência cardíaca, calorias, distância, passos, velocidade e ritmo.
  • A natação oferece suporte a dados de frequência cardíaca, calorias, distância e voltas.

Cliente de monitoramento passivo

Os tipos de dados abaixo são obrigatórios em todos os dispositivos Wear OS para oferecer suporte a apps que monitoram dados de saúde passivamente, como frequência cardíaca e contagem de passos. Cada um desses tipos de dados precisa ser derivado apenas dos dados gerados pelos sensores no smartwatch.

Comportamentos esperados

Para economizar energia, as leituras do sensor recebidas usando o monitoramento passivo são armazenadas no MCU e agrupadas em Recursos de saúde. Esses resultados em lote são retornados em intervalos diferentes, dependendo do comportamento do sistema. Alguns exemplos incluem retornar os lotes quando os buffers do sensor estão cheios ou quando o usuário interage com a tela.

Não presuma intervalos de lotes predefinidos ou previsíveis para nenhum tipo de dado.

Tipos de dados de monitoramento passivo

Métrica Dados esperados Observações
HEART_RATE_BPM Batimentos por minuto [Tipo de dados: Double] Os dispositivos podem retornar leituras de frequência cardíaca em intervalos diferentes. Alguns dispositivos podem fazer leituras a cada segundo. Outros fazem uma leitura a cada 10 minutos. Esses intervalos não são disponibilizados para apps. Eles precisam se adaptar a diferentes intervalos de amostragem.
STEPS_DAILY/STEPS [Tipo de dados: longo] O número de passos por dia é o número total de passos dados desde a última redefinição, que é acionada pelo WHS à meia-noite. Isso inclui todas os passos dados enquanto um exercício ativo está pausado. Passos são um delta granular desde a última verificação.
Distance_DAILY/Distance metros [Tipo de dados: Double] Calculada pelo acelerômetro/passos. Não faça cálculos usando o GPS. Assim os usuários que desativaram os Serviços de localização ainda recebem contagens de passos precisas.
SPEED [metros / segundo] [Tipo de dados: Double]
DIÁRIAS_CALORIAS kCal [Tipo de dados: Double] Calorias do dia, incluindo calorias ativas e BMR. O número de calorias emitido aqui considera a altura, o peso, a idade e o sexo do usuário, conforme especificado nas configurações do sistema. As calorias não são ajustadas de acordo com os dados de perfil do usuário coletados no seu app.
RUNNING_STEPS (opcional) [Tipo de dados: longo] Delta entre passos dados durante um exercício e passos em outras situações. Monitore os dois valores ao mesmo tempo.
WALKING_STEPS (opcional) [Tipo de dados: longo]
ELEVATION_GAIN metros [Tipo de dados: Double] Inclui apenas os deltas positivos de elevação.
ELEVATION_LOSS metros [Tipo de dados: Double] Inclui apenas os deltas negativos de elevação.
ARREDMULTB [Tipo de dados: Double] Pode ser representado como andares "parciais".

Objetivos diários de monitoramento passivo

Métrica Dados esperados Anotações
ETAPAS_DIÁRIAS [Tipo de dados: longo] O total de passos por dia, incluindo os passos dados enquanto um exercício ativo está pausado. É o número total de passos dados desde a última redefinição. O WHS é redefinido à meia-noite.
ARREDMULTB [Tipo de dados: Double] Pode ser representado como andares "parciais" de escadas.
DIÁRIAS_CALORIAS kCal [Tipo de dados: Double] Calorias do dia, incluindo calorias ativas e BMR.
Distance_DAILY metros [Tipo de dados: Double] Calculada pelo acelerômetro ou pela contagem de passos. Não calcule isso usando o GPS para que os usuários que desativaram os Serviços de localização ainda possam receber contagens de passos precisas.
DAILY_ELEVATION_GAIN metros [Tipo de dados: Double] Inclui apenas os deltas positivos de elevação.

MeasureClient

Use o MeasureClient para medir a frequência cardíaca em um determinado momento.

Comportamentos esperados

MeasureClient e PassiveClient são semelhantes em alguns casos. Ambos fornecem estatísticas de saúde não agrupadas em lote e que não são relacionadas a exercícios. Você pode usar ambos para medir a frequência cardíaca, mas a principal diferença é que o MeasureClient inclui a disponibilidade de dados de frequência cardíaca, mas o PassiveClient não inclui informações de disponibilidade.

Tipos de dados

Métrica Dados esperados Observações
HEART_RATE_BPM Batimentos por minuto [Tipo de dados: Double] Também inclui disponibilidade.

Recursos com suporte

Além dos tipos de dados de exercício e de monitoramento passivo, os dispositivos oferecem suporte a outros recursos para acionar eventos, como iniciar um exercício e medir estados como dormindo e acordado. Alguns desses recursos existem em todos os dispositivos, e outros existem apenas em alguns.

Gatilhos de evento

Todos os dispositivos oferecem suporte aos gatilhos comuns abaixo:

  • Objetivos diários de distância e passos.
  • Objetivos de atividade física para passos, distância e duração.

Outros dispositivos podem oferecer suporte a gatilhos de eventos mais avançados. Confira alguns exemplos:

  • Contagem de voltas ao nadar.
  • Objetivos de atividade física para as calorias queimadas.
  • Objetivos de atividade física para velocidade instantânea.

Estados

Todos os dispositivos oferecem suporte a funcionalidades básicas de estado. A funcionalidade de estado indica se um usuário está em um exercício ativo ou não.

Outros dispositivos podem oferecer mais funcionalidades de estado. Algumas outras funcionalidades de estado incluem detectar se um exercício foi pausado ou retomado automaticamente ou quando o usuário está acordado ou dormindo.

Alertas de saúde durante o monitoramento passivo

Alguns dispositivos oferecem suporte a alertas de saúde. Esses recursos não têm suporte de todos os dispositivos. Alguns alertas de saúde incluem a detecção de anormalidades da frequência cardíaca ou a detecção de quedas.