Referência do cliente JavaScript de login do Google

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

Se você encontrar algum problema ao usar a biblioteca, informe-o ao nosso repositório 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 . Você deve chamar esse método antes de chamar os métodos do gapi.auth2.GoogleAuth .

Ao inicializar o objeto GoogleAuth , você configura o objeto com seu ID de cliente OAuth 2.0 e quaisquer opções adicionais que deseja especificar. Em seguida, se o usuário já tiver feito login, o objeto GoogleAuth restaurará o estado de login do usuário da sessão anterior.

Argumentos
params	Um objeto que contém pares de valores-chave de dados de configuração do cliente. Consulte gapi.auth2.ClientConfig para as diferentes propriedades configuráveis. Por exemplo: { client_id: 'CLIENT_ID.apps.googleusercontent.com' }

Devoluções
gapi.auth2.GoogleAuth	O objeto gapi.auth2.GoogleAuth . Use o método then() para obter uma promessa que seja resolvida quando o objeto gapi.auth2.GoogleAuth terminar de inicializar.

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 não suportados), 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 contendo uma propriedade de error , se GoogleAuth não inicializar.

Devoluções
Promessa	Uma Promise que é cumprida quando a função onInit é concluída ou rejeitada se um erro de inicialização for gerado. Ele resolve com o valor retornado da função onInit , se houver.

Atenção: não chame Promise.resolve() e similares com o resultado de gapi.auth2.init() . Como o objeto GoogleAuth retornado implementa o método then() que resolve consigo mesmo, ele criará uma recursão infinita.

Códigos de erro

idpiframe_initialization_failed

Falha ao inicializar um iframe obrigatório do Google, por exemplo, devido a um ambiente não compatível. Uma propriedade de details fornecerá mais informações sobre o erro gerado.

gapi.auth2.ClientConfig

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

Parâmetros
client_id	string	Requerido. O ID do cliente do aplicativo, encontrado e criado no Google Developers Console.
cookie_policy	string	Os domínios para os quais criar cookies de login. Ou 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 estiver configurado como false.
fetch_basic_profile	boolean	Busque as informações básicas do perfil dos usuários quando eles entrarem. Adiciona 'perfil', 'email' e 'openid' aos escopos solicitados. Verdadeiro se não especificado.
hosted_domain	string	O domínio do G Suite ao qual os usuários devem pertencer para fazer login. Isso é suscetível a modificações 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 que você esperava. Você deve solicitar o escopo 'email' ao usar este parâmetro junto com fetch_basic_profile: false .
ux_mode	string	O modo UX a ser usado para o fluxo de login. Por padrão, ele abrirá 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 no final do fluxo de consentimento. O redirect_uri padrão é o URL atual sem parâmetros de consulta e fragmento de hash.
plugin_name	string	Opcional. Se esse valor for definido, novos IDs de cliente criados antes de 29 de julho de 2022 poderão usar a biblioteca mais antiga do Google Platform. Por padrão, os IDs de cliente recém-criados agora são impedidos de usar a Biblioteca de plataforma e, em vez disso, precisam usar a biblioteca mais recente do Google Identity Services. Você pode escolher qualquer valor, um nome descritivo como o nome do produto ou plugin é recomendado para facilitar a 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, obtenha o status de login atual do usuário, obtenha dados específicos do perfil do Google do usuário, solicite escopos adicionais e saia da conta atual.

gapi.auth2.getAuthInstance()

Retorna o objeto GoogleAuth . Você deve inicializar o objeto GoogleAuth com gapi.auth2.init() antes de chamar esse método.

Devoluções
gapi.auth2.GoogleAuth	O objeto gapi.auth2.GoogleAuth . Use este objeto para chamar os métodos do gapi.auth2.GoogleAuth .

GoogleAuth.isSignedIn.get()

Retorna se o usuário atual está conectado no momento.

Devoluções
boleano	true se o usuário estiver conectado ou false se o usuário estiver desconectado ou o objeto GoogleAuth não for inicializado.

GoogleAuth.isSignedIn.listen(ouvinte)

Ouça as alterações no estado de entrada do usuário atual.

Argumentos
listener	Uma função que recebe um valor booleano. listen() passa true para esta função quando o usuário entra e false quando o usuário sai.

GoogleAuth.signIn()

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

Devoluções
Promessa	Uma Promise que é cumprida com a instância GoogleUser quando o usuário autentica e concede os escopos solicitados com êxito ou rejeitada com um objeto que contém uma propriedade de error se ocorrer um erro (veja abaixo os códigos de erro).

Códigos de erro

Consulte GoogleAuth.signIn( options ) .

GoogleAuth.signIn( options )

Conecta o usuário usando as opções especificadas.

Argumentos

options

Ou: Um objeto gapi.auth2.SignInOptions contendo pares chave-valor de parâmetros de entrada. 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');

Devoluções
Promessa	Uma Promise que é cumprida com a instância GoogleUser quando o usuário autentica e concede os escopos solicitados com êxito ou rejeitada com um objeto que contém uma propriedade de error se ocorrer um erro (veja 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 prompt: 'none' . Esta opção não deve ser necessária para usar, pois gapi.auth2.init fará login automaticamente no usuário se estiver conectado anteriormente 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 solicita que o usuário selecione uma conta do Google. Isso permite que um usuário que tenha várias contas selecione entre as várias contas para as quais pode ter sessões atuais. none ( não recomendado ) O servidor de autorização não exibirá nenhuma tela de autenticação ou consentimento do usuário; ele retornará um erro se o usuário ainda não estiver autenticado e não tiver consentido anteriormente com os escopos solicitados. Como gapi.auth2.init fará o login automático de um usuário no aplicativo se estiver conectado anteriormente, chamar signIn({prompt: 'none'}) geralmente falhará.
scope	string	Os escopos a serem solicitados, como uma string delimitada por espaço, sobre os escopos definidos nos parâmetros gapi.auth2.init . Opcional se fetch_basic_profile não estiver configurado como false.
ux_mode	string	O modo UX a ser usado para o fluxo de login. Por padrão, ele abrirá 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 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()

Desconecta a conta atual do aplicativo.

Devoluções
Promessa	Uma Promise que é cumprida quando o usuário é desconectado.

GoogleAuth.disconnect()

Revoga todos os escopos que o usuário concedeu.

GoogleAuth.grantOfflineAccess( options )

Obtenha permissão do usuário para acessar os escopos especificados offline.

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

Devoluções
Promessa	Uma Promise que é cumprida quando o usuário concede os escopos solicitados, passando um objeto contendo o código de autorização para o manipulador de cumprimento da 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 prompt: 'none' . Esta opção não deve ser necessária para usar, pois gapi.auth2.init fará login automaticamente no usuário se estiver conectado anteriormente 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 solicita que o usuário selecione uma conta do Google. Isso permite que um usuário que tenha várias contas selecione entre as várias contas para as quais pode ter sessões atuais. Observe que none não está disponível para o fluxo de código offline.
scope	string	Os escopos a serem solicitados, como uma string delimitada por espaço, sobre os escopos definidos nos parâmetros gapi.auth2.init . Opcional se fetch_basic_profile não estiver configurado como false.

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

Anexa o fluxo de entrada ao manipulador 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 parâmetros de chave-valor. Consulte GoogleAuth.signIn() .
onsuccess	A função a ser chamada após a conclusão do login.
onfailure	A função a ser chamada se a entrada falhar.

Comercial

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

GoogleAuth.currentUser.get()

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

Devoluções
GoogleUser	O usuário atual

GoogleAuth.currentUser.listen( listener )

Ouça as alterações em currentUser.

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

GoogleUser.getId()

Obtenha a string de ID exclusiva do usuário.

Não use os IDs do Google retornados por getId() para comunicar o usuário conectado no momento ao seu servidor de back-end. Em vez disso, envie tokens de ID , que podem ser validados com segurança no servidor.

Devoluções
Fragmento	O ID exclusivo do usuário

GoogleUser.isSignedIn()

Retorna verdadeiro se o usuário estiver conectado.

Devoluções
boleano	Verdadeiro se o usuário estiver conectado

GoogleUser.getHostedDomain()

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

Devoluções
Fragmento	O domínio do G Suite do usuário

GoogleUser.getGrantedScopes()

Obtenha os escopos que o usuário concedeu como uma string delimitada por espaço.

Devoluções
Fragmento	Os escopos concedidos pelo usuário

GoogleUser.getBasicProfile()

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

Não use as informações de perfil do usuário para comunicar o usuário conectado no momento ao seu servidor de back-end. Em vez disso, envie tokens de ID , que podem ser validados com segurança no servidor.

Devoluções
gapi.auth2.BasicProfile	Você pode 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)

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

Argumentos
includeAuthorizationData	Opcional: Um booleano que especifica se deve sempre 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 é true (o valor padrão) e nenhum escopo adicional é solicitado.

Devoluções
gapi.auth2.AuthResponse	Um objeto gapi.auth2.AuthResponse .

GoogleUser.reloadAuthResponse()

Força uma atualização do token de acesso e, em seguida, retorna uma promessa para o novo AuthResponse.

Devoluções
Promise	Uma Promise que é cumprida com o gapi.auth2.AuthResponse recarregado ao recarregar o token OAuth é concluída.

gapi.auth2.AuthResponse

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

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é que o token de acesso expire.
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 expirará.

GoogleUser.hasGrantedScopes( scopes )

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

Argumentos
scopes	Uma sequência de escopos delimitada por espaço.

Devoluções
boleano	Verdadeiro se os escopos foram concedidos

GoogleUser.grant( options )

Solicite escopos adicionais ao usuário.

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

GoogleUser.grantOfflineAccess( options )

Obtenha permissão do usuário para acessar os escopos especificados offline.

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

GoogleUser.disconnect()

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

Elementos da interface do usuário

gapi.signin2.render( id , options )

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

Argumentos
id	A ID do elemento no qual renderizar o botão de login.
options	Um objeto contendo 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 alcance Os escopos a serem solicitados quando o usuário entra (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 Exiba rótulos longos, como "Fazer login com o Google" em vez de "Fazer login" (padrão: false ). Ao usar títulos longos, você deve aumentar 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 ). em sucesso A função de retorno de chamada a ser chamada quando um usuário fizer login com êxito. Essa função deve ter um argumento: uma instância de gapi.auth2.GoogleUser (padrão: nenhum). em fracasso A função de retorno de chamada a ser chamada quando o login falha. Esta função não aceita argumentos (padrão: nenhum).

Avançado

Aviso: esta seção abrange recursos que não são recomendados para a maioria dos casos de uso. Certifique-se de que os métodos descritos nos Guias não funcionem para o seu caso de uso antes de usar esses recursos.

gapi.auth2.authorize( params , callback )

Executa uma autorização OAuth 2.0 única. Dependendo dos parâmetros usados, isso abrirá um pop-up para o fluxo de login do Google ou tentará carregar a resposta solicitada silenciosamente, sem 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 fizer login.
• Seu aplicativo tem sua própria infraestrutura de gerenciamento de sessão e requer o ID Token apenas uma vez para identificar o usuário em seu back-end.
• Vários IDs de cliente são usados ​​na mesma página.

Aviso: não use esse método junto com o gapi.auth2.init recomendado e o fluxo signIn . Esses são dois comportamentos distintos (Autorização para gapi.auth2.authorize vs Autenticação para gapi.auth2.init/signIn ) e terão problemas inesperados se usados ​​no mesmo aplicativo.

Argumentos
params	Um objeto que contém pares de valores-chave de dados de configuração. Consulte gapi.auth2.AuthorizeConfig para 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 êxito 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 ambiente não compatível. Uma propriedade de details 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 prompt: 'none' .

gapi.auth2.AuthorizeConfig

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

Propriedades
client_id	string	Obrigatório . O ID do cliente do aplicativo, encontrado e criado no Google Developers Console.
scope	string	Obrigatório . Os escopos a serem solicitados, como uma string delimitada por espaço.
response_type	string	Uma lista de tipo de resposta delimitada por espaço. O 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 solicita que o usuário selecione uma conta do Google. Isso permite que um usuário que tenha várias contas selecione entre as várias contas para as quais pode ter sessões atuais. none O servidor de autorização não exibirá nenhuma tela de autenticação ou consentimento do usuário; ele retornará um erro se o usuário ainda não estiver autenticado e não tiver consentido anteriormente com 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 . Nota: sob o capô, a biblioteca armazena em cache e atualiza automaticamente o último token de acesso obtido. Ao usar prompt: 'none' , na maioria das vezes, nenhuma solicitação HTTP para o back-end será necessária para obter um token válido.
cookie_policy	string	Os domínios para os quais criar cookies de login. Ou 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 devem pertencer para fazer login. Isso é 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 ID de usuário, de um usuário a ser pré-selecionado no fluxo de entrada. Isso é suscetível a modificação pelo usuário, a menos que prompt: "none" seja usado.
include_granted_scopes	boolean	Se deve solicitar um Token de Acesso que inclua todos os escopos concedidos anteriormente pelo usuário ao aplicativo ou apenas os escopos solicitados na chamada atual. O padrão é true .
plugin_name	string	Opcional. Se definido, os IDs de cliente criados antes de 29 de julho de 2022 podem usar a Biblioteca do Google Platform. Por padrão, os IDs de cliente recém-criados são impedidos de usar a Biblioteca da plataforma e, em vez disso, precisam usar a biblioteca mais recente do Google Identity Services. Você pode escolher qualquer valor, um nome descritivo como o nome do produto ou plugin é recomendado para facilitar a identificação. Exemplo: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

A resposta retornou ao retorno de chamada do método gapi.auth2.authorize .

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