Visão geral

A API Google Health é uma nova API criada do zero que permite aos desenvolvedores consultar dados de usuários do Fitbit. Não é apenas uma atualização, mas uma mudança estratégica para garantir que seus apps sejam seguros, confiáveis e preparados para avanços futuros na tecnologia de saúde. A API oferece um novo console para registrar seus apps, suporte ao Google OAuth 2.0, novos tipos de dados, novo esquema de endpoint e novo formato de resposta.

O guia foi criado para ajudar os desenvolvedores a migrar os apps da API Fitbit Web para a nova API Google Health.

Por que migrar?

Os benefícios de usar a API Google Health são:

  • Segurança aprimorada: conformidade com as práticas recomendadas de segurança do Google, alinhamento com os padrões de segurança, privacidade e identidade do Google.
  • Consistência: elimina inconsistências legadas em formatos de dados, fusos horários, unidades de medida e tratamento de erros para uma experiência de desenvolvedor mais intuitiva.
  • Escalabilidade e preparação para o futuro: projetada para escalonar e atender às demandas futuras e oferece suporte a protocolos modernos, como o gRPC.

Migrar seus usuários

A migração da API Fitbit Web para a API Google Health é mais do que uma atualização técnica. Os usuários precisam autorizar novamente a nova integração devido à mudança na biblioteca OAuth. Não é possível transferir tokens de acesso e de atualização para a API Google Health e fazer com que eles funcionem. Para ajudar na retenção de usuários durante a migração, confira algumas sugestões técnicas e estratégicas para uma migração bem-sucedida.

A estratégia de biblioteca dupla

Como a API Fitbit Web e a API Google Health usam bibliotecas OAuth2 diferentes, é necessário gerenciar um período de "ponte" em que as duas bibliotecas existem na sua base de código.

Gerenciamento de autorização paralela

  • Encapsular clientes: crie uma camada de abstração ou interface para o "Serviço de saúde". Isso permite que o restante do app solicite dados sem saber qual biblioteca (OAuth do Fitbit ou OAuth do Google) está ativa para esse usuário específico.
  • Atualização do esquema de banco de dados: atualize a tabela de usuários para incluir uma oauth_type flag. Por exemplo, use fitbit para o OAuth do Fitbit e google para o OAuth do Google.
    • Novos usuários: use a API Google Health e a biblioteca OAuth do Google como padrão. Defina oauth_type como google.
    • Usuários atuais: mantenha a API Fitbit Web até que eles concluam o fluxo de autorização novamente. Defina oauth_type como fitbit.

O fluxo de autorização novamente "Step-Up"

Em vez de forçar um logout, use uma abordagem de autorização incremental:

  1. Detectar o token de código aberto do Fitbit: quando um usuário da API Fitbit Web abrir o app, acione uma notificação de "Atualização de serviço".
  2. Iniciar o fluxo do OAuth do Google: quando o usuário clicar em "Atualizar", inicie o fluxo da biblioteca OAuth2 do Google.
  3. Substituir e revogar: depois que o token OAuth do Google for recebido, salve-o no perfil do usuário, atualize o oauth_type de fitbit para google e, se possível, revogue programaticamente o token fitbit antigo para manter o perfil de segurança do usuário limpo.

Maximizar a retenção de usuários

A autorização novamente é a "zona de perigo" para o churn. Para evitar que os usuários abandonem o app, siga estas práticas recomendadas de UX:

A comunicação "Valor primeiro"

Não comece com "Atualizamos nossa API". Comece com os benefícios do novo sistema com tecnologia do Google:

  • Segurança aprimorada: mencione a proteção de conta e a autenticação de dois fatores líderes do setor do Google.
  • Confiabilidade: tempos de sincronização mais rápidos e conexões de dados mais estáveis.
  • Limitação de recursos: informe aos usuários que novos recursos e tipos de dados exigem a atualização.

Tempo inteligente

  • Não interrompa tarefas de alto valor: nunca acione a tela de autorização novamente enquanto um usuário estiver no meio de um treino ou registrando alimentos.
  • A fase de "empurrão": nos primeiros 30 dias, use um banner dispensável.
  • A fase de "corte definitivo": só torne a autorização novamente obrigatória após várias semanas de avisos, coincidindo com os prazos oficiais de suspensão da API Fitbit Web.

Comparação do fluxo de migração

Uma distinção visual clara entre os fluxos antigos e novos ajuda os desenvolvedores a entender onde a lógica se bifurca.

Recurso API Fitbit Web (legada) API Google Health (identidade do Google)
Biblioteca de autenticação Código aberto padrão Serviços de Identificação do Google (GIS, na sigla em inglês) / Autenticação do Google
Contas de usuário Credenciais legadas do Fitbit Conta do Google
Tipo de token Acesso / atualização específico do Fitbit Tokens de acesso/atualização emitidos pelo Google
Gerenciamento de escopo Permissões amplas Permissões granulares / incrementais

Gerenciar a nuance da migração de contas

De acordo com a documentação do Fitbit, os usuários que migram a conta para o Google geralmente não perdem as conexões de terceiros imediatamente, mas a mudança na versão da API é um requisito do desenvolvedor.

  • Verificar a validade do token: use um backgroundworker para verificar se os tokens do Fitbit estão falhando com erros "Não autorizado". Isso pode indicar que o usuário migrou a conta, mas o app não acompanhou.
  • Falhas normais: se uma chamada OAuth do Fitbit falhar, redirecione o usuário para uma página personalizada "Reconectar o Fitbit" que usa especificamente o novo fluxo OAuth do Google.