Referência do cliente JavaScript do Login do Google

Esta referência descreve os métodos e atributos do cliente JavaScript que você vai usar para implementar o Login do Google nos seus aplicativos da Web.

Se você encontrar algum problema ao usar a biblioteca, informe-o no nosso repositório do GitHub. .

Configuração de autenticação

Carregue a biblioteca da plataforma de APIs do Google para criar o objeto gapi:

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

Depois que a biblioteca da plataforma for carregada, carregue a biblioteca auth2:

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(params)

Inicializa o objeto GoogleAuth. É necessário chamar esse método antes de chamar os métodos de gapi.auth2.GoogleAuth.

Ao inicializar o objeto GoogleAuth, configure-o com o ID do cliente OAuth 2.0 e as outras opções que queira especificar. Em seguida, se o usuário já tiver feito login, o objeto GoogleAuth vai restaurar o estado de login do usuário da sessão anterior.

Argumentos
params Um objeto que contém pares de chave-valor dos dados de configuração do cliente. Consulte gapi.auth2.ClientConfig para conferir as diferentes propriedades configuráveis. Por exemplo: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Retorna
gapi.auth2.GoogleAuth O objeto gapi.auth2.GoogleAuth. Use o método then() para receber uma promessa que é resolvida quando o objeto gapi.auth2.GoogleAuth termina a inicialização.

GoogleAuth.then(onInit, onError)

Chama a função onInit quando o objeto GoogleAuth é totalmente inicializado. Se um erro for gerado durante a inicialização (isso pode acontecer em navegadores antigos), a função onError será chamada.

Argumentos
onInit A função chamada com o objeto GoogleAuth quando ele é totalmente inicializado.
onError A função chamada com um objeto que contém uma propriedade error, se GoogleAuth não foi inicializado.
Retorna
Promise Uma Promise que é atendida quando a função onInit é concluída ou rejeitada se um erro de inicialização for gerado. Ele é resolvido com o valor retornado da função onInit, se houver.

Códigos de erro

idpiframe_initialization_failed
Falha ao inicializar um iframe necessário do Google, por exemplo, devido a um ambiente sem suporte. Uma propriedade details vai fornecer mais informações sobre o erro gerado.

gapi.auth2.ClientConfig

Interface que representa os diferentes parâmetros de configuração do método gapi.auth2.init.

Parâmetros
client_id string Obrigatório. O ID do cliente do app, encontrado e criado no Console de APIs do Google.
cookie_policy string Os domínios para os quais os cookies de login serão criados. Um URI, single_host_origin ou none. O padrão é single_host_origin se não for especificado.
scope string Os escopos a serem solicitados, como uma string delimitada por espaços. Opcional se fetch_basic_profile não estiver definido como falso.
fetch_basic_profile boolean Buscar as informações básicas de perfil dos usuários quando eles fizerem login. Adiciona "profile", "email" e "openid" aos escopos solicitados. Verdadeiro se não for especificado.
hosted_domain string O domínio do G Suite ao qual os usuários precisam pertencer para fazer login. Isso pode ser modificado pelos clientes. Portanto, verifique a propriedade do domínio hospedado do usuário retornado. Use GoogleUser.getHostedDomain() no cliente e a declaração hd no token de ID no servidor para verificar se o domínio é o esperado.
use_fedcm boolean Opcional, o padrão é True. Ative ou desative o uso de APIs FedCM do navegador durante o login.
ux_mode string O modo de UX a ser usado para o fluxo de login. Por padrão, ele vai abrir o fluxo de consentimento em um pop-up. Os valores válidos são: popup e redirect.
redirect_uri string Se você usar ux_mode='redirect', esse parâmetro vai permitir que você substitua o redirect_uri padrão que será usado no final do fluxo de consentimento. O redirect_uri padrão é o URL atual sem parâmetros de consulta e fragmento de hash.
enable_granular_consent boolean Opcional. Se é necessário ativar permissões granulares. Se definido como false, as permissões mais granulares da Conta Google serão desativadas para IDs de cliente OAuth criados antes de 2019. Não há efeito para IDs de cliente OAuth criados em 2019 ou depois, já que permissões mais granulares estão sempre ativadas para eles.
plugin_name string Opcional. Se esse valor for definido, os novos IDs de cliente criados antes de 29 de julho de 2022 poderão usar a biblioteca antiga do Google Platform. Por padrão, os IDs de cliente recém-criados agora não podem usar a biblioteca da plataforma e precisam usar a biblioteca mais recente dos Serviços de Identificação do Google. Você pode escolher qualquer valor. Um nome descritivo, como o nome do produto ou do plug-in, é recomendado para identificação. Exemplo: plugin_name: 'YOUR_STRING_HERE'

Autenticação

GoogleAuth é uma classe Singleton que fornece métodos para permitir que o usuário faça login com uma Conta do Google, receba o status de login atual do usuário, receba dados específicos do perfil do Google do usuário, solicite escopos adicionais e faça logout da conta atual.

gapi.auth2.getAuthInstance()

Retorna o objeto GoogleAuth. É necessário inicializar o objeto GoogleAuth com gapi.auth2.init() antes de chamar esse método.

Retorna
gapi.auth2.GoogleAuth O objeto gapi.auth2.GoogleAuth. Use esse objeto para chamar os métodos de gapi.auth2.GoogleAuth.

GoogleAuth.isSignedIn.get()

Retorna se o usuário atual fez login.

Retorna
Booleano true se o usuário estiver conectado ou false se o usuário estiver desconectado ou se o objeto GoogleAuth não estiver inicializado.

GoogleAuth.isSignedIn.listen(listener)

Detecte mudanças no estado de login do usuário atual.

Argumentos
listener Uma função que recebe um valor booleano. listen() transmite true para essa função quando o usuário faz login e false quando o usuário sai.

GoogleAuth.signIn()

Faz o login do usuário com as opções especificadas para gapi.auth2.init().

Retorna
Promise Uma Promise que é atendida com a instância GoogleUser quando o usuário autentica e concede os escopos solicitados ou é rejeitada com um objeto que contém uma propriedade error se ocorrer um erro. Consulte a próxima seção para ver os códigos de erro.

Códigos de erro

Veja GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Faz o login do usuário usando as opções especificadas.

Argumentos
options Possibilidades:
  • Um objeto gapi.auth2.SignInOptions que contém pares de chave-valor de parâmetros de login. Por exemplo: 
    {
  scope: 'profile email'
}
  • Uma instância de gapi.auth2.SigninOptionsBuilder. Por exemplo:
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
Retorna
Promise Um Promise que é atendido com a instância GoogleUser quando o usuário autentica e concede os escopos solicitados ou é rejeitado com um objeto que contém uma propriedade error se um erro ocorreu (consulte abaixo os códigos de erro).

Códigos de erro

popup_closed_by_user
O usuário fechou o pop-up antes de concluir o fluxo de login.
access_denied
O usuário negou a permissão para os escopos necessários.
immediate_failed
Nenhum usuário pode ser selecionado automaticamente sem solicitar o fluxo de consentimento. Erro gerado ao usar signIn com a opção prompt: 'none'. Essa opção não precisa ser usada, porque gapi.auth2.init faz login automaticamente no usuário se ele já tiver feito login durante uma sessão anterior.

gapi.auth2.SignInOptions

Interface que representa os diferentes parâmetros de configuração do método GoogleAuth.signIn(options).

Parâmetros
prompt string Força um modo específico para o fluxo de consentimento. Opcional.
Os valores possíveis são:
  • consent
    O servidor de autorização solicita o consentimento do usuário antes de retornar as informações ao aplicativo.
  • select_account
    O servidor de autorização pede que o usuário selecione uma Conta do Google. Isso permite que um usuário com várias contas selecione entre as várias contas em que ele pode ter sessões atuais.
  • none (não recomendado)
    O servidor de autorização não vai mostrar nenhuma tela de autenticação ou consentimento do usuário. Ele vai retornar um erro se o usuário ainda não tiver sido autenticado e não tiver consentido anteriormente com os escopos solicitados.
    Como o gapi.auth2.init faz login automático de um usuário no aplicativo se ele já tiver feito login, o chamado signIn({prompt: 'none'}) geralmente falha.
scope string Os escopos a serem solicitados, como uma string delimitada por espaços, além dos escopos definidos nos parâmetros gapi.auth2.init. Opcional se fetch_basic_profile não for definido como falso.
ux_mode string O modo de UX a ser usado para o fluxo de login. Por padrão, ele vai abrir o fluxo de consentimento em um pop-up. Os valores válidos são: popup e redirect.
redirect_uri string Se você usar ux_mode='redirect', esse parâmetro vai permitir que você substitua o redirect_uri padrão que será usado no final do fluxo de consentimento. O redirect_uri padrão é o URL atual sem parâmetros de consulta e fragmento de hash.

GoogleAuth.signOut()

Sai da conta atual do aplicativo.

Retorna
Promise Um Promise que é cumprido quando o usuário é desconectado.

GoogleAuth.disconnect()

Revoga todos os escopos concedidos pelo usuário.

GoogleAuth.grantOfflineAccess(options)

Receber permissão do usuário para acessar os escopos especificados off-line.

Argumentos
options Um objeto gapi.auth2.OfflineAccessOptions que contém pares de chave-valor de parâmetros. Por exemplo: 
{
  scope: 'profile email'
}
Retorna
Promise Um Promise que é atendido quando o usuário concede os escopos solicitados, transmitindo um objeto que contém o código de autorização para o gerenciador de atendimento do Promise. Por exemplo: 
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Códigos de erro

popup_closed_by_user
O usuário fechou o pop-up antes de concluir o fluxo de consentimento.
access_denied
O usuário negou a permissão para os escopos necessários.
immediate_failed
Nenhum usuário pode ser selecionado automaticamente sem solicitar o fluxo de consentimento. Erro gerado ao usar signIn com a opção prompt: 'none'. Essa opção não precisa ser usada, porque gapi.auth2.init faz o login automático do usuário se ele já tiver feito login durante uma sessão anterior.

gapi.auth2.OfflineAccessOptions

Interface que representa os diferentes parâmetros de configuração do método GoogleAuth.grantOfflineAccess(options).

Parâmetros
prompt string Força um modo específico para o fluxo de consentimento. Opcional.
Os valores possíveis são:
  • consent
    O servidor de autorização solicita o consentimento do usuário antes de retornar as informações ao aplicativo.
  • select_account
    O servidor de autorização pede que o usuário selecione uma Conta do Google. Isso permite que um usuário com várias contas selecione entre as várias contas em que ele pode ter sessões atuais.
scope string Os escopos a serem solicitados, como uma string delimitada por espaços, além dos escopos definidos nos parâmetros gapi.auth2.init. Opcional se fetch_basic_profile não for definido como falso.

GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)

Anexa o fluxo de login ao gerenciador de cliques do contêiner especificado.

Argumentos
container O ID ou uma referência ao elemento div ao qual anexar o manipulador de cliques.
options Um objeto que contém pares de chave-valor de parâmetros. Consulte GoogleAuth.signIn().
onsuccess A função a ser chamada após o término do login.
onfailure A função a ser chamada se o login falhar.

Usuários

Um objeto GoogleUser representa uma conta de usuário. Os objetos GoogleUser são normalmente obtidos chamando GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

Retorna um objeto GoogleUser que representa o usuário atual. Em uma instância GoogleAuth recém-inicializada, o usuário atual não foi definido. Use o método currentUser.listen() ou o GoogleAuth.then() para receber uma instância GoogleAuth inicializada.

Retorna
GoogleUser O usuário atual

GoogleAuth.currentUser.listen(listener)

Detectar mudanças no currentUser.

Argumentos
listener Uma função que usa um parâmetro GoogleUser. listen transmite a essa função uma instância de GoogleUser em cada mudança que modifica currentUser.

GoogleUser.getId()

Receba a string de ID exclusiva do usuário.

Retorna
String O ID exclusivo do usuário

GoogleUser.isSignedIn()

Retorna verdadeiro se o usuário estiver conectado.

Retorna
Booleano Verdadeiro se o usuário fez login

GoogleUser.getHostedDomain()

Receber o domínio do G Suite do usuário, se ele tiver feito login com uma conta do G Suite.

Retorna
String O domínio do G Suite do usuário

GoogleUser.getGrantedScopes()

Receba os escopos concedidos pelo usuário como uma string delimitada por espaços.

Retorna
String Os escopos concedidos pelo usuário

GoogleUser.getBasicProfile()

Receba as informações básicas de perfil do usuário.

Retorna
gapi.auth2.BasicProfile É possível recuperar as propriedades de gapi.auth2.BasicProfile com os seguintes métodos:
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getGivenName()
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

Receba o objeto de resposta da sessão de autenticação do usuário.

Argumentos
includeAuthorizationData Opcional:um booleano que especifica se sempre vai retornar um token de acesso e escopos. Por padrão, o token de acesso e os escopos solicitados não são retornados quando fetch_basic_profile é verdadeiro (o valor padrão) e nenhum escopo adicional é solicitado.
Retorna
gapi.auth2.AuthResponse Um objeto gapi.auth2.AuthResponse.

GoogleUser.reloadAuthResponse()

Força uma atualização do token de acesso e retorna uma promessa para a nova AuthResponse.

Retorna
Promise Um Promise que é preenchido com o gapi.auth2.AuthResponse recarregado quando o token OAuth é recarregado.

gapi.auth2.AuthResponse

A resposta retornada ao chamar os métodos GoogleUser.getAuthResponse(includeAuthorizationData) ou GoogleUser.reloadAuthResponse().

Propriedades
access_token string O token de acesso foi concedido.
id_token string O token de ID concedido.
scope string Os escopos concedidos no token de acesso.
expires_in number O número de segundos até o token de acesso expirar.
first_issued_at number O carimbo de data/hora em que o usuário concedeu os escopos solicitados pela primeira vez.
expires_at number O carimbo de data/hora em que o token de acesso vai expirar.

GoogleUser.hasGrantedScopes(scopes)

Retorna verdadeiro se o usuário concedeu os escopos especificados.

Argumentos
scopes Uma string de escopos delimitada por espaços.
Retorna
Booleano Verdadeiro se os escopos foram concedidos

GoogleUser.grant(options)

Solicite outros escopos ao usuário.

Consulte GoogleAuth.signIn() para conferir a lista de parâmetros e o código de erro.

GoogleUser.grantOfflineAccess(options)

Receber permissão do usuário para acessar os escopos especificados off-line.

Argumentos
options Um objeto gapi.auth2.OfflineAccessOptions que contém pares de chave-valor de parâmetros. Por exemplo: 
{
  scope: 'profile email'
}

GoogleUser.disconnect()

Revoga todos os escopos que o usuário concedeu para o aplicativo.

Elementos da interface

gapi.signin2.render(id, options)

Renderiza um botão de login no elemento com o ID fornecido, usando as configurações especificadas pelo objeto options.

Argumentos
id O ID do elemento em que o botão de login será renderizado.
options Um objeto que contém as configurações a serem usadas para renderizar o botão. Por exemplo: 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
Você pode especificar as seguintes opções:
Parâmetros
escopo Os escopos a serem solicitados quando o usuário fizer login (padrão: profile).
largura A largura do botão em pixels (padrão: 120).
altura A altura do botão em pixels (padrão: 36).
longtitle Mostre rótulos longos, como "Fazer login com o Google" em vez de "Fazer login" (padrão: false). Quando você usa títulos longos, aumente a largura do botão em relação ao padrão.
tema O tema de cores do botão: light ou dark (padrão: light).
onsuccess A função de callback a ser chamada quando um usuário faz login. Essa função precisa usar um argumento: uma instância de gapi.auth2.GoogleUser (padrão: nenhum).
onfailure A função de callback a ser chamada quando a ação de login falhar. Essa função não recebe argumentos (padrão: nenhum).

Avançado

gapi.auth2.authorize(params, callback)

Realiza uma autorização única do OAuth 2.0. Dependendo dos parâmetros usados, isso vai abrir um pop-up para o fluxo de login do Google ou tentar carregar a resposta solicitada silenciosamente, sem a interação do usuário.

Alguns casos de uso em que esse método é útil incluem:

  • Seu aplicativo só precisa solicitar um endpoint da API do Google uma vez, por exemplo, para carregar os vídeos favoritos do YouTube do usuário na primeira vez que ele faz login.
  • O aplicativo tem a própria infraestrutura de gerenciamento de sessões e só precisa do token de ID uma vez para identificar o usuário no back-end.
  • Vários IDs de cliente são usados na mesma página.
Argumentos
params Um objeto que contém pares de chave-valor de dados de configuração. Consulte gapi.auth2.AuthorizeConfig para conferir as diferentes propriedades configuráveis. Por exemplo: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback Uma função chamada com um objeto gapi.auth2.AuthorizeResponse após a conclusão da solicitação (com sucesso ou com falha).

Exemplo

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

Códigos de erro

idpiframe_initialization_failed
Falha ao inicializar um iframe necessário do Google, por exemplo, devido a um ambiente sem suporte. Uma propriedade details vai fornecer mais informações sobre o erro gerado.
popup_closed_by_user
O usuário fechou o pop-up antes de concluir o fluxo de login.
access_denied
O usuário negou a permissão para os escopos necessários.
immediate_failed
Nenhum usuário pode ser selecionado automaticamente sem solicitar o fluxo de consentimento. Erro gerado ao usar signIn com a opção prompt: 'none'.

gapi.auth2.AuthorizeConfig

Interface que representa os diferentes parâmetros de configuração do método gapi.auth2.authorize.

Propriedades
client_id string Obrigatório. O ID do cliente do app, encontrado e criado no Console de APIs do Google.
scope string Obrigatório. Os escopos a serem solicitados, como uma string delimitada por espaços.
response_type string Uma lista de tipos de resposta delimitados por espaços. O valor padrão é 'permission'. Os valores possíveis são:
  • id_token, para recuperar um token de ID
  • permission (ou token), para recuperar um token de acesso
  • code, para recuperar um código de autorização
prompt string Força um modo específico para o fluxo de consentimento. Os valores possíveis são:
  • consent
    O servidor de autorização solicita o consentimento do usuário antes de retornar as informações ao aplicativo.
  • select_account
    O servidor de autorização pede que o usuário selecione uma Conta do Google. Isso permite que um usuário com várias contas selecione entre as várias contas em que ele pode ter sessões atuais.
  • none
    O servidor de autorização não vai mostrar nenhuma tela de autenticação ou consentimento do usuário. Ele vai retornar um erro se o usuário ainda não tiver sido autenticado e não tiver dado consentimento para os escopos solicitados.
    Se code for solicitado como tipo de resposta, o código retornado só poderá ser trocado por um access_token, não por um refresh_token.
cookie_policy string Os domínios para os quais os cookies de login serão criados. Um URI, single_host_origin ou none. O padrão é single_host_origin se não for especificado.
hosted_domain string O domínio do G Suite ao qual os usuários precisam pertencer para fazer login. Isso pode ser modificado pelos clientes. Portanto, verifique a propriedade do domínio hospedado do usuário retornado.
login_hint string O e-mail ou ID do usuário que será pré-selecionado no fluxo de login. Isso pode ser modificado pelo usuário, a menos que prompt: "none" seja usado.
include_granted_scopes boolean Define se é necessário solicitar um token de acesso que inclua todos os escopos concedidos anteriormente pelo usuário ao app ou apenas os escopos solicitados na chamada atual. O valor padrão é true.
enable_granular_consent boolean Opcional. Se é necessário ativar permissões granulares. Se definido como false, as permissões mais granulares da Conta do Google serão desativadas para IDs de cliente OAuth criados antes de 2019. Não há efeito para IDs de cliente OAuth criados em 2019 ou depois, já que permissões mais granulares estão sempre ativadas para eles.
plugin_name string Opcional. Se definido, os IDs de cliente criados antes de 29 de julho de 2022 poderão usar a biblioteca do Google Platform. Por padrão, os IDs de cliente recém-criados não podem usar a biblioteca da plataforma e precisam usar a biblioteca mais recente dos Serviços de Identificação do Google. Você pode escolher qualquer valor, mas um nome descritivo, como o nome do produto ou do plug-in, é recomendado para facilitar a identificação. Exemplo: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

A resposta retornada ao callback do método gapi.auth2.authorize.

Propriedades
access_token string O token de acesso foi concedido. Presente apenas se permission ou token forem especificados no response_type.
id_token string O token de ID concedido. Presente apenas se id_token foi especificado no response_type.
code string O código de autorização foi concedido. Presente apenas se code foi especificado no response_type.
scope string Os escopos concedidos no token de acesso. Presente apenas se permission ou token tiver sido especificado no response_type.
expires_in number O número de segundos até o token de acesso expirar. Presente apenas se permission ou token for especificado no response_type.
first_issued_at number O carimbo de data/hora em que o usuário concedeu os escopos solicitados pela primeira vez. Presente apenas se permission ou token tiver sido especificado no response_type.
expires_at number O carimbo de data/hora em que o token de acesso vai expirar. Presente apenas se permission ou token for especificado no response_type.
error string Quando a solicitação falha, ela contém o código de erro.
error_subtype string Quando a solicitação falha, ela pode conter informações adicionais sobre o código de erro também retornado.