Referência do cliente JavaScript do Login do Google

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

Se você encontrar qualquer problema ao usar a biblioteca, informe nossa equipe 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 do gapi.auth2.GoogleAuth.

Ao inicializar o objeto GoogleAuth, você o configura com o ID do cliente OAuth 2.0 e outras opções que quiser especificar. Em seguida, se o usuário já tiver feito login, o objeto GoogleAuth vai restaurar o estado de login 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 os valores propriedades configuráveis. 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 é resolvido quando o objeto gapi.auth2.GoogleAuth termina inicializando.

GoogleAuth.then(onInit, onError)

Chama a função onInit quando o objeto GoogleAuth está totalmente inicializado. Se ocorrer um erro durante a inicialização (isso pode acontecer em navegadores antigos incompatíveis), a função onError será chamada.

Argumentos
onInit A função chamada com o objeto GoogleAuth quando está totalmente inicializado.
onError A função chamada com um objeto que contém uma propriedade error. se a inicialização de GoogleAuth falhar.
Retorna
Promise Uma Promise que é preenchida quando a onInit função foi concluída ou rejeitada se um erro de inicialização tiver sido 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 obrigatório do Google, por exemplo, devido a um de nuvem. Uma propriedade details dará 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. Pode ser 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ço. Opcional se fetch_basic_profile não está definido como falso.
fetch_basic_profile boolean Buscar usuários informações básicas de perfil ao fazer login. Adiciona "perfil" e "e-mail" e "openid" aos escopos solicitados. Verdadeiro se não for especificado.
hosted_domain string O domínio do G Suite em que os usuários precisam pertencer a um usuário para fazer login. Isso é suscetível à modificação pelos clientes. Por isso, verifique propriedade de domínio hospedado do usuário retornado. Usar GoogleUser.getHostedDomain() em o cliente e a declaração hd no token de ID do para verificar se o domínio é o que você esperava.
use_fedcm boolean Opcional, o padrão é True. Ativar ou desativar o uso de APIs FedCM do navegador durante o login.
ux_mode string O modo de UX a ser usado no fluxo de login. Por padrão, ele abre o fluxo de consentimento. em um pop-up. Os valores válidos são: popup e redirect.
redirect_uri string Se estiver usando ux_mode='redirect', esse parâmetro permite substituir o redirect_uri padrão que vai ser usado ao final do fluxo de consentimento. A O padrão redirect_uri é o URL atual sem parâmetros de consulta e hash. de dados.
enable_granular_consent boolean Opcional. Se quer ativar granular do Google Cloud. Se definido como false, os parâmetros mais granulares As permissões da conta serão desativadas para IDs do cliente OAuth criados antes de de 2019. Nenhum efeito para os IDs do cliente OAuth criados durante ou após 2019, pois permissões mais granulares estão sempre ativadas para eles.
plugin_name string Opcional. Se esse valor for definido, os novos IDs do cliente criados antes de julho A partir de 29 de junho de 2022, será possível usar a biblioteca mais antiga da Plataforma Google. Por padrão, os Client-IDs recém-criados estão impedidos de usar biblioteca do Platform e, em vez disso, precisa usar a versão mais recente do Biblioteca de serviços. Você pode escolher qualquer valor, um nome descritivo como nome do produto ou plug-in é recomendado para identificação. Exemplo: plugin_name: 'YOUR_STRING_HERE'

Autenticação

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

gapi.auth2.getAuthInstance()

Retorna o objeto GoogleAuth. Inicialize 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 métodos do gapi.auth2.GoogleAuth.

GoogleAuth.isSignedIn.get()

Informa se o usuário atual está conectado.

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

GoogleAuth.isSignedIn.listen(listener)

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

Argumentos
listener Uma função que usa um valor booleano. listen() cartão true para essa função quando o usuário fizer login. false quando o usuário sair.

GoogleAuth.signIn()

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

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

Códigos de erro

Consulte 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 dos parâmetros de login. 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 Uma Promise que é preenchida com a instância de GoogleUser quando o o usuário autentica e concede os escopos solicitados ou é rejeitado com um objeto contendo uma propriedade error se ocorrer um erro (consulte os códigos de erro abaixo).

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 quando usando signIn com a opção prompt: 'none'. Essa opção não deve ser porque o gapi.auth2.init fará o login do usuário automaticamente se conectado anteriormente em uma sessão anterior.

gapi.auth2.SignInOptions

Interface que representa os diferentes parâmetros de configuração do 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 e
    O servidor de autorização solicita o consentimento do usuário antes de retornar. informações ao aplicativo.
  • select_account e
    O servidor de autorização solicita 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 disponíveis para as sessões atuais.
  • none (não recomendado)
    O servidor de autorização não exibirá as autenticações nem o consentimento do usuário telas; isso retornará um erro se o usuário ainda não estiver autenticado e não consentiu anteriormente com os escopos solicitados.
    Como o gapi.auth2.init faz o login de um usuário automaticamente no do aplicativo se já tiver feito login, chamando signIn({prompt: 'none'}) normalmente falha.
scope string Os escopos a serem solicitados, como uma string delimitada por espaços, sobre os escopos definidos no Parâmetros gapi.auth2.init. Opcional se fetch_basic_profile não estiver definido como falso.
ux_mode string O modo de UX a ser usado no fluxo de login. Por padrão, ele abre o fluxo de consentimento. em um pop-up. Os valores válidos são: popup e redirect.
redirect_uri string Se estiver usando ux_mode='redirect', esse parâmetro permite substituir o redirect_uri padrão que será usado ao final do consentimento fluxo O redirect_uri padrão é o URL atual sem a consulta. e o fragmento de hash.

GoogleAuth.signOut()

Desconecta a conta atual do aplicativo.

Retorna
Promise Uma Promise que é preenchida quando o usuário é assinado para fora.

GoogleAuth.disconnect()

Revoga todos os escopos concedidos pelo usuário.

GoogleAuth.grantOfflineAccess(options)

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

Argumentos
options Um gapi.auth2.OfflineAccessOptions que contém pares de chave-valor de parâmetros. Exemplo: 
{
  scope: 'profile email'
}
Retorna
Promise Uma Promise que é preenchida quando o usuário concede o escopos solicitados, passando um objeto contendo o código de autorização para o gerenciador de fulfillment do Promise. 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 finalizar 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 a solicitação do fluxo de consentimento. Erro gerado quando usando signIn com a opção prompt: 'none'. Essa opção não deve ser porque o gapi.auth2.init fará o login do usuário automaticamente se conectado anteriormente em uma sessão anterior.

gapi.auth2.OfflineAccessOptions

Interface que representa os diferentes parâmetros de configuração do 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 e
    O servidor de autorização solicita o consentimento do usuário antes de retornar. informações ao aplicativo.
  • select_account e
    O servidor de autorização solicita 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 disponíveis para as sessões atuais.
.
scope string Os escopos a serem solicitados, como uma string delimitada por espaços, sobre os escopos definidos no Parâmetros gapi.auth2.init. Opcional se fetch_basic_profile não estiver 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 do elemento div ou uma referência a ele anexar o gerenciador 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 a conclusão do login.
onfailure Função a ser chamada em caso de falha no login.

Usuários

Um objeto GoogleUser representa uma conta de usuário. Objetos GoogleUser normalmente são obtidos chamando GoogleAuth.currentUser.get() (em inglês).

GoogleAuth.currentUser.get()

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

Retorna
GoogleUser O usuário atual

GoogleAuth.currentUser.listen(listener)

Detectar mudanças em currentUser.

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

GoogleUser.getId()

Recebe a string de ID exclusivo do usuário.

Retorna
String O ID exclusivo do usuário

GoogleUser.isSignedIn()

Retorna "true" se o usuário está conectado.

Retorna
Booleano Verdadeiro se o usuário estiver conectado

GoogleUser.getHostedDomain()

Verifique 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()

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

Retorna
String Os escopos concedidos pelo usuário

GoogleUser.getBasicProfile()

Conseguir as informações básicas do 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 um token de acesso será sempre retornado. 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 o novo AuthResponse.

Retorna
Promise Uma Promise que é preenchida com o gapi.auth2.AuthResponse ao recarregar o O token OAuth foi concluído.

gapi.auth2.AuthResponse

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

Propriedades
access_token string O token de acesso 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 expira.

GoogleUser.hasGrantedScopes(scopes)

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

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

GoogleUser.grant(options)

Solicitar escopos adicionais ao usuário.

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

GoogleUser.grantOfflineAccess(options)

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

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

GoogleUser.disconnect()

Revoga todos os escopos concedidos pelo usuário ao 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. Exemplo: 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
 É possível 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).
título longo Mostrar 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 do 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 fizer login. Esta função deve ter um argumento: uma instância de gapi.auth2.GoogleUser (padrão: nenhum).
onfailure A função de callback a ser chamada em caso de falha no login. Essa função não aceita argumentos (o padrão é nenhum).

Avançado

gapi.auth2.authorized(params, callback)

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

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

  • Seu aplicativo só precisa solicitar um endpoint de API do Google uma vez, por exemplo, para carregar aos vídeos favoritos do YouTube na primeira vez que ele fizer login.
  • Seu aplicativo tem a própria infraestrutura de gerenciamento de sessão e exige apenas o Token de ID uma vez para identificar o usuário no back-end.
  • Vários Client-IDs são usados na mesma página.
.
Argumentos
params Um objeto que contém pares de chave-valor dos dados de configuração. Consulte gapi.auth2.AuthorizeConfig para o e diferentes propriedades configuráveis. Exemplo: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback Uma função chamada com um gapi.auth2.AuthorizeResponse objeto 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 obrigatório do Google, por exemplo, devido a um de nuvem. Uma propriedade details dará 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 a solicitação do fluxo de consentimento. Erro gerado quando usando signIn com a opção prompt: 'none'.

gapi.auth2.AuthorizeConfig

Interface que representa os diferentes parâmetros de configuração do 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ço.
response_type string Uma lista de tipos de resposta delimitados por espaços. O valor padrão é 'permission'. As possíveis são:
  • id_token, para extrair um token de ID
  • permission (ou token) para extrair 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 e
    O servidor de autorização solicita o consentimento do usuário antes de retornar. informações ao aplicativo.
  • select_account e
    O servidor de autorização solicita 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 disponíveis para as sessões atuais.
  • none e
    O servidor de autorização não exibirá as autenticações nem o consentimento do usuário telas; isso retornará um erro se o usuário ainda não estiver autenticado e não consentiu anteriormente com os escopos solicitados.
    Se code for solicitado como tipo de resposta, o código retornado será pode 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. Pode ser 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 em que os usuários precisam pertencer a um usuário para fazer login. Isto é suscetível a modificações pelos clientes. Portanto, verifique a propriedade do domínio hospedado do usuário retornado.
login_hint string O e-mail, ou User-ID, de um usuário a ser pré-selecionado no fluxo de login. Isso é suscetível a modificação pelo usuário, a menos que prompt: "none" seja usado.
include_granted_scopes boolean Se é necessário solicitar um token de acesso que inclua todos os escopos concedidos anteriormente pelo usuário ao app ou apenas aos escopos solicitados na chamada atual. O valor padrão é true.
enable_granular_consent boolean Opcional. Se quer ativar granular do Google Cloud. Se definido como false, os parâmetros mais granulares As permissões da conta serão desativadas para IDs do cliente OAuth criados antes de de 2019. Nenhum efeito para os IDs do cliente OAuth criados durante ou após 2019, pois permissões mais granulares estão sempre ativadas para eles.
plugin_name string Opcional. Se definido, os IDs do cliente criados antes de 29 de julho de 2022 poderão usar o Biblioteca da Plataforma Google. Por padrão, os Client-IDs recém-criados são bloqueados da biblioteca da plataforma e, em vez disso, precisa utilizar a versão mais recente com a biblioteca Identity Services. Você pode escolher qualquer valor, um nome descritivo como o nome do produto ou do plug-in, para facilitar a identificação. Exemplo: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

A resposta retornada ao retorno de chamada do gapi.auth2.authorize.

Propriedades
access_token string O token de acesso concedido. Presente apenas se permission ou token foram especificado no response_type.
id_token string O token de ID concedido. Presente apenas se id_token for especificado no response_type.
code string O código de autorização concedido. Presente apenas se code for especificado no response_type.
scope string Os escopos concedidos no token de acesso. Presente apenas se permission ou token foi especificado em response_type.
expires_in number O número de segundos até o token de acesso expirar. Presente apenas se permission ou token foi especificado em 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 foi especificado no response_type.
expires_at number O carimbo de data/hora em que o token de acesso expira. Presente apenas se permission ou token foi especificado em response_type.
error string Quando a solicitação falhou, ela contém o código do erro.
error_subtype string Quando a solicitação falhou, pode conter informações adicionais para o código de erro também retornados.