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ê precisa 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 à 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 quer usar com a API Google Health, faça login na conta de administrador desse projeto primeiro. Em seguida, selecione o projeto 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 perguntarem "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. Quando a configuração estiver concluída, copie os valores de ID do cliente e chave secreta do cliente do OAuth 2.0 e faça o download do JSON de credenciais na sua máquina local.
Ativar a API e receber um ID do cliente OAuth 2.0

Se você quiser configurar manualmente seu projeto na nuvem do Google, ou verificar a configuração e recuperar suas credenciais novamente:

  1. Ative a API Google Health na página Ativação de 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 sandbox ou ambiente de teste separado. Todos os seus ambientes chamam a API Google Health de produção, então você gerencia a separação de ambientes no nível do projeto 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, preparação e produção. Cada projeto gerencia o próprio cliente OAuth 2.0, tela de permissão e assinantes de webhook.
  • Não use seu projeto na nuvem de produção do Google Cloud nem o cliente OAuth 2.0 dele para testes, porque as mudanças nesse projeto afetam diretamente seu app de produção.
  • Primeiro, desenvolva e teste em um projeto que não seja de produção e, depois, aplique as mudanças ao projeto de produção quando estiver tudo 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 revisão de segurança de terceiros. Confira mais informações na Central de Ajuda de verificação de apps OAuth.

Adicionar escopos

Você precisa especificar os escopos que seu 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 voltar à página "Acesso a dados".
  4. Clique em Salvar.

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

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

Atualizar escopos

Para pedir que o usuário autorize novamente seu app, defina o parâmetro "prompt" como "consent" na solicitação de autenticação. Quando prompt=consent é incluído, a tela de permissão é mostrada 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 mudar escopos usando o parâmetro prompt=consent, siga estas etapas:

  1. Identifique a lista completa de escopos que seu aplicativo precisa. Isso inclui 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. Adicione prompt=consent aos parâmetros de URI de autenticação. Isso força o servidor de autorização a pedir 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 com todos os escopos solicitados será exibida. 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 o conjunto completo de escopos.

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

Bibliotecas de cliente OAuth2

A lista de bibliotecas de cliente 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 guias personalizadas do Chrome no Android ou ASWebAuthenticationSession no iOS) e nunca use WebViews incorporados, que bloqueiam chaves de acesso e interrompem fluxos do OAuth do Google. Consulte as práticas recomendadas do recurso Fazer login com o Google para orientação.

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 Google Health para dispositivos móveis e 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 concluir as seguintes etapas no app Google Health para dispositivos móveis antes de iniciar o fluxo de consentimento do OAuth no seu app:

  1. Baixe e abra o app 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 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 detalhes sobre como processar contas desvinculadas (400 ACCOUNT_NOT_LINKED), consulte Processar Contas do Google desvinculadas.

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 da implementação, incluindo as solicitações HTTP e os parâmetros específicos 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": "refresh-token",
  "refresh_token_expires_in": 112154
}

Quando atualizar um token

Atualize os tokens de atualização sob demanda como parte da progressão natural de uma sessão ativa do usuário quando os tokens de acesso expiram ou estão prestes a expirar. Evite atualizar tokens em lotes. Por exemplo, usando um job ou serviço cron programado para atualizar tokens de todos os usuários em um horário fixo.

Não é recomendável atualizar tokens em lotes pelos seguintes motivos:

  • A atualização em lote impede o alinhamento das atualizações de token com padrões de sincronização de usuários ativos. Embora seja possível usar a chamada Get Devices para conferir o último horário de sincronização de um usuário, isso exige um escopo do 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 sobrecarga de processamento redundante para seus sistemas e servidores do Google.
  • Se ocorrer um problema de rede ou uma interrupçã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 dos 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 acontecem com menos frequência e geram uma enxurrada 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 ter erros de autenticação intermitentes.

Comportamento do token durante o teste

Saiba 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 do OAuth estiver configurada com um status de publicação "Teste", os tokens de atualização emitidos serão baseados em tempo e vão expirar após sete dias. Durante esse período, você vai receber um único token de atualização que permanece válido e pode ser usado para receber novos tokens de acesso até 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 sem uso por um período prolongado (normalmente seis meses).

Para uma experiência de usuário perfeita, publique o aplicativo antes que ele seja movido 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 de amostra ou simulados 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, 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.
  • Ativar o rastreamento móvel:ative o MobileTrack no app Google Health e caminhe com seu dispositivo móvel.
  • Registrar dados manualmente:insira manualmente 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 aos endpoints da 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 REST.

Proteção entre contas (API RISC)

Ative o compartilhamento e a 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 da conexão da interface. A ativação da API RISC é opcional.

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

  1. Abra a página da API RISC no console do Google Cloud. Verifique se o projeto usado 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, crie e registre 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.