Comece sua migração ou o desenvolvimento de um novo app hoje mesmo! Os apps com mais de 100 usuários podem enviar a solicitação de verificação a partir de 30 de março.

Para garantir uma experiência perfeita aos usuários, recomendamos aguardar até o fim de maio de 2026 para lançar oficialmente sua integração e se alinhar à descontinuação da conta legada do Fitbit. De agora até o final de maio, podem ocorrer mudanças incompatíveis à medida que respondemos ao feedback dos desenvolvedores.

Guia de migração

A API Google Health é uma nova API criada do zero que permite aos desenvolvedores consultar dados do usuário do Fitbit. Essa não é apenas uma atualização, mas uma mudança estratégica para garantir que seus apps sejam seguros, confiáveis e estejam prontos para futuros avanços na tecnologia de saúde. A API é compatível com um novo console para registrar seus apps, suporte ao OAuth 2.0 do Google, 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: compliance 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.
Escalonabilidade e preparação para o futuro: projetado para escalonar e atender às demandas futuras e compatível com protocolos modernos, como o gRPC.

Registro do app

Todos os apps da API Google Health precisam ser registrados usando o console do Google Cloud, que serve como um hub central para gerenciar todos os seus apps do Google.

Para instruções sobre como registrar seu app, siga as etapas em Como começar. Confira as diferenças que você vai notar ao registrar seus apps.

	API Fitbit Web	API Google Health
Links públicos	https://dev.fitbit.com/apps	https://console.cloud.google.com
Adicionar um novo app	Clique em Registrar um novo app.	Criar um projeto do Google Cloud Ative a API Google Health.
Informações básicas	Campos a serem preenchidos: Nome do aplicativo Descrição URL do site do aplicativo Organização URL do site da organização URL dos Termos de Serviço URL da Política de Privacidade	Campos a serem preenchidos: Nome do aplicativo E-mail para suporte Público-alvo (interno ou externo) E-mail de contato Ícone do logotipo URL do site do aplicativo URL da Política de Privacidade URL dos Termos de Serviço Domínio autorizado
Tipos de aplicativos	Um desenvolvedor precisa selecionar: Servidor Cliente Pessoal	Aplicativo da Web Android Extensão do Chrome iOS TVs App para computador Plataforma Universal do Windows
ID do cliente	Registrado quando as configurações do aplicativo são salvas.	Registrado separadamente
Tipo de acesso	O acesso de leitura e gravação é controlado no nível do app	O acesso de leitura e gravação é controlado no nível do escopo
Outros URLs	URL de redirecionamento: site para onde os usuários são redirecionados depois de autorizar os escopos.	Origens JavaScript autorizadas: origem HTTP que hospeda o aplicativo da web. URL de redirecionamento: site para onde os usuários são redirecionados depois de autorizar os escopos.

Implementação do OAuth

Os apps da API Google Health só são compatíveis com as bibliotecas de cliente do Google OAuth2. As bibliotecas de cliente estão disponíveis para frameworks conhecidos, o que simplifica a implementação do OAuth 2.0. As diferenças entre as bibliotecas do Google OAuth2 e as de código aberto são as seguintes:

	API Fitbit Web	API Google Health
Suporte à biblioteca OAuth2	Código aberto	Bibliotecas de cliente do Google OAuth2
Funcionalidade	Inconsistente em várias plataformas	Consistente em todas as plataformas
URL de autorização	https://www.fitbit.com/oauth2/authorize	https://accounts.google.com/o/oauth2/v2/auth
URL do token	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Tempo de vida do token de acesso	8 horas	1 hora
Tamanho do token de acesso	1.024 bytes	2.048 bytes
Token de atualização	Os tokens de atualização são gerados ao usar o fluxo de concessão de código de autorização. Só é possível gerar um token de atualização por usuário. Os tokens nunca expiram e só podem ser usados uma vez.	Para gerar um token de atualização, a string de autorização precisa conter o parâmetro de consulta "access_type=offline". Vários tokens de atualização podem ser criados para um único usuário. Os tokens de atualização podem ser baseados em tempo. Eles expiram se não forem usados em seis meses, se o usuário conceder acesso por tempo determinado ou se o app estiver no modo "Teste". Consulte Validade do token de atualização para mais detalhes.
Token Response (em inglês)	A resposta JSON contém: token de acesso expiração do token de acesso escopos tipo de token token de atualização ID do usuário	A resposta JSON contém: token de acesso expiração do token de acesso escopos tipo de token token de atualização Para receber o ID do usuário, use o endpoint users.getIdentity.

Os usuários do Fitbit precisam dar consentimento novamente para sua nova integração porque o app está usando uma biblioteca OAuth diferente. Não é possível transferir tokens de acesso e de atualização para a API Google Health e fazer com que eles funcionem.

Escopos

Você precisa atualizar sua solicitação de autorização para usar os escopos da API Google Health. Os escopos definem se o app oferece suporte a operações de leitura ou gravação. Não use escopos que não são necessários para seu app. Você sempre pode adicionar mais escopos depois, se o design do app mudar.

Os escopos da API Google Health são um URL HTTP que começa com https://www.googleapis.com/auth/googlehealth.{scope}. Por exemplo, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Mapeamentos de escopo

Confira como os escopos da API Fitbit Web são mapeados para os escopos da API Google Health:

*Tabela: mapeamentos de escopo da API Fitbit Web para a API Google Health*
Escopos da API Fitbit Web	Escopos da API Google Health
atividade	.activity_and_fitness .activity_and_fitness.readonly
cardio_fitness	.activity_and_fitness .activity_and_fitness.readonly
frequência cardíaca	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
local	.location.readonly
nutrição	.nutrition .nutrition.readonly
oxygen_saturation	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
perfil	.profile .profile.readonly
respiratory_rate	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
configurações	.settings .settings.readonly
sono	.sleep .sleep.readonly
temperatura	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
peso	.health_metrics_and_measurements .health_metrics_and_measurements.readonly

Tipos de dados

Confira uma lista dos tipos de dados da API Google Health e como eles são mapeados para a API Fitbit Web.

*Tabela: mapeamentos de tipo de dados da API Fitbit Web para a API Google Health*
Tipo de dados da API Fitbit Web	Tipo de dados da API Google Health ID do endpoint
Minutos na faixa ativa	Minutos na faixa ativa `active-zone-minutes`
Contém mudanças nos níveis de atividade do usuário.	Nível de atividade `activity-level`
Elevação	Altitude `altitude`
Gordura corporal	Gordura corporal `body-fat`
`caloriesOut` em cada faixa de frequência cardíaca	Calorias na zona de frequência cardíaca `calories-in-heart-rate-zone`
Resumo da VFC	Variabilidade da frequência cardíaca diária `daily-heart-rate-variability`
Resumo de SpO₂	Saturação de oxigênio diária `daily-oxygen-saturation`
Frequência cardíaca em repouso	Frequência cardíaca em repouso diária `daily-resting-heart-rate`
Temperatura da pele	Derivações diárias da temperatura do sono `daily-sleep-temperature-derivations`
Distância	Distância `distance`
Atividade gravada	Exercício `exercise`
Andares	Andares `floors`
Frequência cardíaca	Frequência cardíaca `heart-rate`
VFC intradiária	Variabilidade da frequência cardíaca `heart-rate-variability`
SPO₂ intradiário	Saturação de oxigênio `oxygen-saturation`
Valor de VO₂ máximo quando o usuário corre	VO₂ máx. da corrida `run-vo2-max`
Série temporal de atividade: minutos sedentários	Período sedentário `sedentary-period`
Sono	Dormir `sleep`
Etapas	Etapas `steps`
Atividade `caloriesOut`	Total de calorias `total-calories`
Valor de VO₂ máx.	VO₂ máx. `vo2-max`
Peso	Peso `weight`

Endpoints

Os endpoints REST adotam uma sintaxe consistente para todos os tipos de dados.

Endpoint de serviço: o URL HTTP de base muda para https://health.googleapis.com.
Sintaxe de endpoint: a API Google Health é compatível com um número limitado de endpoints, que podem ser usados pela maioria dos tipos de dados aceitos. Isso fornece uma sintaxe consistente para todos os tipos de dados e facilita o uso dos endpoints.
Identificador do usuário: o ID do usuário ou "me" precisa ser especificado na sintaxe do endpoint. Ao usar "me", o ID do usuário é inferido do token de acesso.

Exemplo: confira um exemplo do endpoint GET Profile chamado usando a API Google Health.

GET https://health.googleapis.com/v4/users/me/profile

Mapeamentos de endpoint

Consulte a tabela Disponibilidade de tipos de dados para ver uma lista dos tipos de dados disponíveis e os métodos de API compatíveis.

Tipo de endpoint da API Fitbit Web	API Google Health
GET (Log \| Summary \| Daily Summary) em que você está solicitando um único dia de dados	Método dailyRollup com `windowSize` = 1 dia
GET (intraday) em que você está solicitando dados granulares	Método list
GET (série temporal) por data ou intervalo	Método rollUp ou dailyRollUp, incluindo um período
GET (lista de registros)	Método list
CRIAR E ATUALIZAR registros	Método patch
EXCLUIR registros	Método batchDelete
GET Profile	users.getProfile retorna as informações específicas do usuário. users.getSettings retorna as unidades e os fusos horários do usuário.
ATUALIZAR perfil	users.updateProfile modifica as informações específicas do usuário. users.updateSettings modifica as unidades e os fusos horários do usuário.
Receber o ID do usuário	O users.getIdentity retorna o ID de usuário legado do Fitbit e do Google do usuário.

Migrar seus usuários

Migrar da API Fitbit Web para a API Google Health é mais do que uma atualização técnica. Seus usuários precisam dar consentimento novamente para a nova integração devido à mudança na biblioteca OAuth. Não é possível transferir tokens de acesso e atualização para a API Google Health. 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 ambas as bibliotecas existem na sua base de código.

Gerenciamento de autorização paralela

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

Fluxo de novo consentimento "Step-Up"

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

Detectar 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 do serviço".
Iniciar o fluxo do Google OAuth: quando o usuário clicar em "Atualizar", inicie o fluxo da biblioteca do Google OAuth2.
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 renovação do consentimento é a "zona de perigo" para o churn. Para evitar que os usuários abandonem o app, siga estas práticas recomendadas de UX:

Comunicação "Prioridade ao valor"

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

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

Programação inteligente

Não interrompa tarefas de alto valor: nunca acione a tela de novo consentimento enquanto um usuário estiver no meio de um treino ou registrando alimentos.
A fase de "incentivo": nos primeiros 30 dias, use um banner dispensável.
A fase de "corte definitivo": só torne o novo consentimento obrigatório após várias semanas de avisos, coincidindo com os prazos oficiais de descontinuaçã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 ramifica.

Recurso	API Fitbit Web (legado)	API Google Health (Google-Identity)
Biblioteca de autenticação	Código aberto padrão	Serviços de Identificação do Google (GIS) / Autenticação do Google
Contas de usuário	Credenciais legadas do Fitbit	Conta do Google
Tipo de token	Acesso / atualização específica do Fitbit	Tokens de acesso/atualização emitidos pelo Google
Gerenciamento de escopo	Permissões amplas	Permissões granulares / incrementais

Lidar com 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 mudar a versão da API é uma exigência 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 ainda não foi atualizado.
Falhas normais: se uma chamada do OAuth do Fitbit falhar, redirecione o usuário para uma página personalizada "Reconectar o Fitbit" que usa especificamente o novo fluxo do OAuth do Google.

Exemplo de código

Para migrar da API Fitbit Web legada para a API Google Health, você vai passar das bibliotecas gerais do OAuth2 para a biblioteca de autenticação do Google. A seguir, há uma sugestão de arquitetura e uma implementação de pseudocódigo escrita em JavaScript para lidar com esse estado de "biblioteca dupla".

1. A "troca de middleware"

Como não é possível migrar todos os usuários de uma vez, o back-end precisa determinar qual biblioteca usar com base no apiVersion atual do usuário armazenado no banco de dados.

Implementação

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. Migrar o fluxo de UX

Para maximizar a retenção, use um padrão "Interromper e fazer upgrade". Isso garante que o usuário não seja forçado a fazer login novamente até que já esteja engajado com o app.

Lógica de redirecionamento

Quando um usuário da API Fitbit Web acessar um recurso específico, acione a migração:

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3. Principais transições técnicas

Ao escrever seus scripts de migração do JavaScript, tenha em mente estas diferenças:

Recurso	API Fitbit Web (legado)	API Google Health (Google-Identity)
Endpoint do token	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Biblioteca de autenticação	Código aberto padrão	Autenticação do Google
Escopo	atividade	https://www.googleapis.com/auth/googlehealth.activity_and_fitness
ID do usuário	ID codificado do Fitbit retornado na resposta /oauth2/token	ID do usuário retornado do endpoint users.getIdentity

4. Lista de verificação de retenção

Persistência de sessão: não limpe a sessão antiga da API Fitbit Web do usuário até que o access_token da API Google Health seja verificado e salvo no seu banco de dados.
Revogação automática: depois que a migração da API Google Health for concluída, use uma solicitação POST para o endpoint de revogação legado do Fitbit: https://api.fitbit.com/oauth2/revoke. Assim, o usuário não vê permissões do app "duplicadas" nas configurações do Fitbit.
Tratamento de erros: se uma chamada do Fitbit retornar um erro 401 Unauthorized, redirecione automaticamente para o fluxo do OAuth do Google em vez de mostrar uma mensagem de erro.

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