Configurar o Google Cloud e o OAuth

O acesso à API Google Health é fornecido pelo Google Cloud. Para ativar a API e autorizar uma Conta do Google, você vai precisar de um projeto do Google Cloud.

Seja você um desenvolvedor da API Fitbit ou um novo usuário da API Google Health, é necessário concluir esta etapa para fazer chamadas para a API.

Criar um projeto e um cliente OAuth

Use o botão Ativar a API e receber um ID do cliente OAuth 2.0 para ativar a API Google Health e receber um ID do cliente OAuth 2.0:

  1. Se você já tiver um projeto na nuvem do Google Cloud que queira usar para a API Google Health, faça login na conta de admin desse projeto primeiro. Em seguida, selecione o projeto atual na lista de projetos disponíveis depois de clicar no botão. Caso contrário, crie um novo projeto.
  2. Selecione Servidor da Web quando aparecer a pergunta "De onde você está ligando?".
  3. Insira https://www.google.com como o valor de URIs de redirecionamento autorizados. Um URI de redirecionamento é necessário para receber um código de autorização usando o OAuth 2.0.
  4. Depois de concluir a configuração, copie os valores do ID do cliente OAuth 2.0 e da chave secreta do cliente e faça o download do JSON de credenciais para sua máquina local.
Ativar a API e receber um ID do cliente OAuth 2.0

Se você quiser configurar manualmente o projeto do Google Cloud ou verificar a configuração e recuperar as credenciais novamente:

  1. Ative a API Google Health na página Ativação da API.
  2. Receba um ID do cliente OAuth 2.0 na página Credenciais.

Para mais informações sobre como configurar o OAuth 2.0 usando o console do Google, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Usar projetos separados para preparo e produção

A API Google Health não oferece um ambiente de sandbox ou de preparo separado. Todos os ambientes chamam a API Google Health de produção. Portanto, você gerencia a separação de ambientes no nível do projeto na nuvem do Google Cloud.

Ao configurar ambientes para seu app, siga estas práticas recomendadas:

  • Crie projetos separados do Google Cloud para seus ambientes de desenvolvimento, preparo e produção. Cada projeto gerencia o próprio cliente OAuth 2.0, a tela de permissão e os assinantes de webhook.
  • Não use o projeto na nuvem de produção do Google Cloud ou o cliente OAuth 2.0 dele para testes, porque as mudanças nesse projeto afetam diretamente o app de produção.
  • Desenvolva e teste primeiro em um projeto que não seja de produção e, em seguida, aplique as mudanças ao projeto de produção quando estiver pronto.
  • Use tags no console do Google Cloud para distinguir visualmente seus projetos por ambiente. Para instruções, consulte Designar ambientes de projeto com tags.

Adicionar usuários de teste

Por padrão, os clientes OAuth recém-criados estão em um estado não verificado com um limite de 100 usuários para fins de teste e produção. Para ativar a autorização durante esse período, adicione manualmente o endereço de e-mail de cada usuário à lista de usuários de teste na configuração do projeto.

Atualize a lista de usuários de teste na página Público-alvo:

  1. Nessa página, o "Status de publicação" precisa estar definido como Teste, e o "Tipo de usuário" como Externo.
  2. Na seção "Usuários de teste", clique em + Adicionar usuários. Insira o endereço de e-mail de todos os usuários de teste que podem conceder ao app permissão para acessar os dados de saúde deles.
  3. Clique em Salvar.

Para oferecer suporte a mais de 100 usuários com a API Google Health, é necessário concluir uma análise de segurança de terceiros. Confira mais informações na Central de Ajuda sobre a verificação de apps OAuth.

Monitorar os limites de taxa de concessão de tokens OAuth

O Google Cloud aplica uma limitação de taxa às concessões de token OAuth para controlar a velocidade com que seu app pode integrar ou autenticar novamente os usuários. Se você espera exceder 10.000 inscrições ou reautenticações de usuários em um período de 24 horas, solicite uma cota maior com antecedência. Para mais informações, consulte Limitação de taxa de aplicativos OAuth.

Adicionar escopos

Especifique os escopos que o cliente pode chamar na página Acesso a dados:

  1. Nessa página, clique em Adicionar ou remover escopos.
  2. Na coluna "API", pesquise "API Google Health". Selecione os escopos necessários para seu aplicativo.
  3. Depois de selecionar todos os escopos necessários, clique em Atualizar para retornar à página "Acesso a dados".
  4. Clique em Salvar.

Antes de selecionar os escopos, revise a implementação do escopo.

Você concluiu a configuração do ID do cliente e agora pode fazer chamadas para a API Google Health.

Atualizar escopos

Para solicitar que o usuário autorize novamente o app, defina o parâmetro prompt como consent na solicitação de autenticação. Quando prompt=consent é incluído, a tela de permissão é exibida sempre que o app solicita autorização de escopos de acesso, mesmo que todos os escopos tenham sido concedidos anteriormente ao projeto das APIs do Google.

Para adicionar ou alterar escopos usando o parâmetro prompt=consent, siga estas etapas:

  1. Identifique a lista completa de escopos que seu aplicativo precisa. Isso deve incluir os escopos atuais e os novos que você precisa adicionar.

  2. Modifique o parâmetro de escopo no URL de autorização para incluir a lista atualizada de valores de escopo separados por espaços.

  3. Anexe prompt=consent aos parâmetros de URI de autenticação. Isso força o servidor de autorização a solicitar o consentimento do usuário antes de retornar informações ao cliente.

    O exemplo a seguir mostra uma solicitação GET HTTPS para o endpoint de autorização do OAuth 2.0 do Google solicitando vários escopos com prompt=consent anexado:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Quando o usuário seguir o link atualizado, uma página de consentimento será apresentada com todos os escopos solicitados. Depois que o usuário clicar em "Continuar" ou "Permitir", você vai receber um novo código de autorização que pode ser trocado por tokens que abrangem todo o conjunto de escopos.

    Inclua prompt=consent somente quando necessário, como quando você precisa receber um novo token de atualização ou quando os escopos solicitados mudaram.

Bibliotecas de cliente do OAuth2

A lista de bibliotecas de cliente do OAuth2 disponíveis usadas para integração com frameworks conhecidos pode ser encontrada em Como usar o OAuth 2.0 para acessar as APIs do Google.

Ao implementar o OAuth do Google em apps para dispositivos móveis ou computadores, sempre use navegadores do sistema, como as guias personalizadas do Chrome no Android ou ASWebAuthenticationSession no iOS, e nunca use WebViews incorporadas, que bloqueiam chaves de acesso e interrompem os fluxos do OAuth do Google. Consulte as práticas recomendadas do recurso Fazer login com o Google para orientações.

Antes de um usuário passar pelo fluxo de consentimento do OAuth 2.0 do Google no seu app, ele precisa fazer login no app para dispositivos móveis Google Health para vincular o Google Health à Conta do Google. O OAuth 2.0 do Google autentica qualquer Conta do Google válida e não pode verificar se a conta tem um perfil ativo do Google Health durante a tela de permissão.

Instrua os usuários a seguir estas etapas no app para dispositivos móveis Google Health antes de iniciar o fluxo de consentimento do OAuth no seu app:

  1. Baixe e abra o app para dispositivos móveis Google Health na Google Play Store ou na App Store da Apple.
  2. Toque em Fazer login com o Google e selecione a Conta do Google que você quer conectar ao app.
  3. Siga as instruções no app para criar um novo perfil do Google Health ou siga as etapas de migração da conta do Fitbit para transferir uma conta do Fitbit para a Conta do Google.

Depois de trocar o código de autorização por tokens OAuth, chame o endpoint users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) para verificar se a Conta do Google do usuário está vinculada ao Google Health antes de marcar a conta como conectada no seu app. Para saber como lidar com contas não vinculadas (400 ACCOUNT_NOT_LINKED), consulte Processar Contas do Google não vinculadas.

Tokens de atualização

Para manter o acesso de longo prazo às APIs do Google sem exigir a reautenticação constante do usuário, seu aplicativo precisa usar um token de atualização. Para detalhes abrangentes de implementação, incluindo as solicitações HTTP específicas e os parâmetros necessários, consulte a documentação da plataforma de identidade do Google.

Para trocar um token de atualização por um token de acesso, faça uma chamada HTTPS POST para o endpoint de token do OAuth 2.0 do Google. O snippet a seguir mostra um exemplo de solicitação e resposta:

Solicitação

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Resposta

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token_expires_in": 112154
}

Quando atualizar um token

Atualize os tokens de atualização on demand como parte da progressão natural da sessão ativa de um usuário quando os tokens de acesso estiverem expirados ou próximos de expirar. Evite atualizar tokens de atualização em lotes (por exemplo, usando um job ou serviço cron programado para atualizar tokens de atualização de todos os usuários em um horário fixo).

Não recomendamos atualizar tokens de atualização em lotes pelos seguintes motivos:

  • A atualização em lote impede o alinhamento das atualizações de token com os padrões de sincronização de usuários ativos. Embora seja possível usar a chamada Get Devices para ver o horário da última sincronização de um usuário, isso requer um escopo OAuth adicional que os usuários não são obrigados a aprovar.
  • O processamento em lote atualiza tokens que não precisam ser atualizados, causando uma sobrecarga de processamento redundante para seus sistemas e para os servidores do Google.
  • Se ocorrer um problema de rede ou uma interrupção do serviço do servidor durante uma atualização em lote, todos os tokens de usuário afetados serão impactados de uma só vez. A atualização individual de tokens durante a progressão natural das sincronizações de usuários isola o impacto de falhas temporárias em um único usuário.
  • Diagnosticar problemas é mais difícil com jobs em lote. Como as solicitações em lote ocorrem com menos frequência e geram um fluxo de entradas de registro de uma só vez, é mais difícil identificar o início de um incidente.
  • Picos de alta simultaneidade em solicitações de token durante execuções em lote aumentam a probabilidade de atingir limites de taxa ou de ocorrer erros de autenticação intermitentes.

Comportamento do token durante o teste

Esteja ciente de como os tokens de atualização se comportam dependendo do status de publicação do seu projeto do Google Cloud:

  • Modo de teste: se a tela de permissão OAuth estiver configurada com um status de publicação "Teste", os tokens de atualização emitidos serão baseados em tempo e expirarão após sete dias. Durante esse período, você vai receber um único token de atualização que permanece válido e utilizável para receber novos tokens de acesso até atingir a data de validade.
  • Modo publicado: quando o app é movido para o status "Em produção", os tokens de atualização geralmente não expiram, a menos que sejam revogados ou permaneçam não utilizados por um período prolongado (normalmente seis meses).

Para uma experiência do usuário integrada, publique o aplicativo antes de movê-lo para um ambiente de produção para evitar expirações de token de sete dias.

Gerar dados de amostra

O Google não fornece dados de saúde simulados ou de amostra pré-preenchidos. Para testar sua integração, gere seus próprios dados de teste. Use um dos seguintes métodos para gerar dados de amostra para seus usuários de teste:

  • Use um tracker: use um tracker Fitbit, um Pixel Watch ou outro smartwatch compatível com o app Google Health e caminhe para gerar dados de passos, frequência cardíaca e treino.
  • Ative o monitoramento móvel: ative o MobileTrack no app Google Health e caminhe com seu dispositivo móvel.
  • Registrar dados manualmente: insira manualmente as métricas de saúde (como sono, peso, ingestão de água ou alimentos) no app Google Health.
  • Gravar dados usando a API: envie solicitações de gravação (como POST ou PATCH) diretamente para os endpoints de API REST para preencher dados de maneira programática. Para mais detalhes sobre como criar e atualizar pontos de dados, consulte a documentação de referência da REST.

Proteção entre contas (API RISC)

Ative o Compartilhamento e Coordenação de Riscos e Incidentes (RISC, na sigla em inglês) se quiser receber notificações sobre mudanças nos tokens de evento ou na vinculação de contas, como contas desconectadas ou tokens revogados, para limpar os tokens armazenados e atualizar o status de conexão da interface. A ativação da API RISC é opcional.

Para ativar a API RISC no seu projeto na nuvem do Google Cloud:

  1. Abra a página da API RISC no console do Google Cloud. Verifique se o projeto que você usa para a API Google Health está selecionado.
  2. Leia os Termos do RISC e entenda os requisitos.
  3. Clique em Ativar se você concordar com os termos.

Depois de ativar a API, você precisa criar e registrar um endpoint HTTPS para receber e validar os tokens de evento enviados pelo Google.

Para mais informações sobre a Proteção entre Contas e o RISC, consulte Proteger contas de usuário com a Proteção entre Contas.