Planejar a performance

Recomendamos aderir às diretrizes de práticas recomendadas abaixo para garantir que o app tenha um bom desempenho com a plataforma Conexão Saúde.

Gravar dados

Os apps só podem gravar dados de origem própria na Conexão Saúde.

Se os dados no seu app tiverem sido importados de outro, a responsabilidade vai ser transferida para o outro app gravar os próprios dados na Conexão Saúde.

Também é uma boa ideia implementar uma lógica que processe exceções de gravação, como dados fora dos limites ou um erro interno do sistema. É possível aplicar as estratégias de espera e nova tentativa em um mecanismo de agendamento de jobs. Se a gravação na Conexão Saúde falhar, o app precisa conseguir passar desse ponto de exportação. Não se esqueça de registrar e informar erros para ajudar no diagnóstico.

Ao rastrear dados, há algumas sugestões que você pode seguir, dependendo da maneira como seu app grava dados.

Rastreamento passivo

Esse tipo de rastreamento inclui apps que gravam dados de forma passiva sobre o condicionamento físico ou saúde do usuário, como a gravação contínua em segundo plano dos passos ou da frequência cardíaca.

Seu app precisa gravar dados periodicamente na Conexão Saúde destas formas:

  • Em cada sincronização, grave apenas os dados novos e atualize os que foram modificados desde a última sincronização.
  • Separe as solicitações em, no máximo, 1.000 registros para cada pedido de gravação.
  • Use o WorkManager para programar tarefas periódicas em segundo plano com um período de pelo menos 15 minutos.

  • Faça com que as tarefas sejam executadas apenas quando o dispositivo estiver inativo e não estiver com pouca bateria.

    val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

Rastreamento ativo

Isso inclui apps que executam rastreamento baseado em eventos, como exercícios e sono, ou entrada manual do usuário, como nutrição. Esses registros são criados quando o app está em primeiro plano ou em eventos raros em que o app é usado algumas vezes por dia.

Confira se o app não mantém a Conexão Saúde em execução durante todo o evento.

Os dados precisam ser gravados na Conexão Saúde de duas maneiras:

  • Sincronizar dados na Conexão Saúde após a conclusão de um evento. Por exemplo, sincronize os dados quando o usuário encerrar uma sessão de exercício rastreada.
  • Agende uma tarefa única usando o WorkManager para sincronizar dados mais tarde.

Taxa de amostragem

Ao gravar dados na Conexão Saúde, use taxas de amostragem adequadas para ajudar a reduzir a carga de armazenamento. Por exemplo, vale a pena considerar a frequência com que os dados de contagem de passos precisam ser registrados ou o tipo de dados de taxa de amostragem vinculados a um treino ativo, por exemplo, a velocidade.

Nem todos os tipos de dados exigem a mesma taxa de amostragem. Há poucos benefícios em atualizar os dados de contagem de passos a cada segundo, ao contrário de uma cadência menos frequente, como a cada 60 segundos. No entanto, taxas de amostragem maiores podem oferecer aos usuários uma visão mais detalhada e granular dos dados de saúde e condicionamento físico. As frequências de taxa de amostragem precisam encontrar um equilíbrio entre detalhes e desempenho.

Sincronizar dados

Os fatores abaixo afetam o processo de sincronização.

Expiração do token

Como um token de mudanças não usado expira após 30 dias, é necessário usar uma estratégia de sincronização que evite perder informações nesse caso. Sua estratégia pode incluir as abordagens abaixo:

  • Pesquise no repositório de dados do seu app o registro consumido mais recentemente que também tem um id da Conexão Saúde.
  • Solicite registros da Conexão Saúde que começam com um carimbo de data/hora específico. Depois, insira ou atualize esses registros no repositório de dados do app.
  • Solicite um token de mudanças para reservá-lo para a próxima vez que for necessário.

Estratégias de gestão de mudanças recomendadas

Caso seu app receba tokens de mudanças inválidos ou expirados, recomendamos as estratégias de gerenciamento abaixo, dependendo de como o token será aplicado na sua lógica:

  • Ler e eliminar a duplicação de todos os dados. Essa é a estratégia ideal.
    • Armazenar o carimbo de data/hora da última vez que os dados foram lidos na Conexão Saúde.
    • Na expiração do token, leia novamente todos os dados do carimbo de data/hora mais recente ou dos últimos 30 dias. Em seguida, exclua os dados lidos anteriormente usando identificadores.
    • O ideal é implementar IDs dos clientes porque eles são necessários para atualizações de dados.
  • Ler somente os dados desde o último carimbo de data/hora de leitura. Isso resulta em algumas discrepâncias de dados relacionados ao tempo de expiração do token de mudanças, mas o período é mais curto, o que pode ser de algumas horas a alguns dias.
    • Armazenar o carimbo de data/hora da última vez que os dados foram lidos na Conexão Saúde.
    • Quando o token expirar, leia todos os dados a partir desse carimbo de data/hora.
  • Excluir e ler os dados dos últimos 30 dias. Isso é mais consistente com o que acontece na primeira integração.
    • Exclua todos os dados da Conexão Saúde lidos pelo app nos últimos 30 dias.
    • Depois da exclusão, leia todos os dados de novo.
  • Ler dados dos últimos 30 dias sem eliminar duplicações. Essa é a estratégia menos indicada e resulta na exibição de dados duplicados para os usuários.
    • Exclua todos os dados da Conexão Saúde lidos pelo app nos últimos 30 dias.
    • Permita entradas duplicadas.

Tokens de mudanças de tipos de dados

Se o app consumir mais de um tipo de dado de forma independente, use tokens de mudança separados para cada tipo. Use uma lista de vários tipos de dados com a API Changes Sync apenas se eles forem consumidos em conjunto ou se não forem usados.

Leituras em primeiro plano

Os apps só podem ler dados da Conexão Saúde enquanto estão em primeiro plano. Ao sincronizar dados da Conexão Saúde, o acesso a ela pode ser interrompido a qualquer momento. Por exemplo, o app precisa processar interrupções durante uma sincronização ao ler uma grande quantidade de dados da Conexão Saúde e continuar na próxima vez que for aberto.

Importar marcações de tempo

Como o app não pode ser notificado sobre novos dados, ele precisa verificar novos dados em dois pontos:

  • Sempre que o app ficar ativo em primeiro plano. Nesse caso, use eventos do ciclo de vida.
  • Periodicamente, enquanto o app permanecer em primeiro plano. Notifique os usuários quando novos dados estiverem disponíveis. Dessa forma, eles podem atualizar a tela para refletir as mudanças.

Limitações de taxa

Em raras circunstâncias, a Conexão Saúde aplica limites de taxa às solicitações do app. Isso é feito para limitar o impacto na bateria e no desempenho do dispositivo.

  • Recomendamos seguir as práticas recomendadas para evitar que as solicitações do seu app sejam rejeitadas devido à limitação de taxa.
  • Os apps precisam ser resilientes em relação à limitação de taxa. Por exemplo, dados em segundo plano podem ser gravados durante a próxima tarefa periódica, no caso de solicitações falharem devido à limitação de taxa.

Integrar seu app

Muitos apps têm um fluxo de integração personalizado, como instruções sobre recursos ou pedidos de consentimento do usuário. Recomendamos que os desenvolvedores exportem uma atividade de integração que a Conexão Saúde inicia quando o usuário interage com o app pela primeira vez. Para fazer isso, adicione o seguinte ao manifesto:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

O suporte para esse recurso ainda não está disponível para o Android 14, mas será lançado em breve.

Quando um usuário tentar conectar seu app à Conexão Saúde, a atividade exportada será iniciada. Essa atividade precisa fazer o seguinte:

  • Mostrar todas as instruções relevantes ao usuário, como explicar quais dados são gravados ou lidos.
  • Pedir o consentimento do usuário, se necessário.
  • Fazer uma solicitação de permissão à Conexão Saúde.
  • Realizar qualquer outra lógica específica do aplicativo, como agendar um worker periódico.
  • Depois de concluída, permita que o usuário dispense a atividade.

Para apps que não exportam uma atividade de integração, a Conexão Saúde leva o usuário para a tela Gerenciar permissões quando ele tenta conectar o app. Isso pode ser aceitável para apps em que as permissões concedidas são o único pré-requisito para a integração funcionar.

A atividade de integração pode ser iniciada mais de uma vez, por exemplo, se o usuário revogar as permissões do app e depois reconectar.