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 algum problema ao usar a biblioteca, informe-o no nosso repositório do GitHub (link em inglês).
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 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 será resolvida quando o objeto gapi.auth2.GoogleAuth terminar a inicialização.
|
GoogleAuth.then(onInit, onError)
Chama a função onInit quando o objeto GoogleAuth
está totalmente
inicializado. Se um erro for gerado 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
inicializada.
|
onError |
A função chamada com um objeto que contém uma propriedade error , se GoogleAuth não for inicializado.
|
Retorna | |
---|---|
Promise | Um Promise preenchido quando a função onInit é concluída ou rejeitado 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 obrigatório do Google, por exemplo, devido a um ambiente
sem suporte. 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. Um URI, single_host_origin ou none . Se não for especificado, o padrão será single_host_origin . |
scope |
string |
Os escopos a serem solicitados, como uma string delimitada por espaço. Essa propriedade é opcional quando
fetch_basic_profile não está definido como "false". |
fetch_basic_profile |
boolean |
Obter informações básicas do 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 em que os usuários precisam pertencer a um usuário para fazer login. Como ele é suscetível à modificação pelos clientes, 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.
|
use_fedcm |
boolean |
Opcional, o padrão é True . Ativar ou desativar o uso das
APIs FedCM do navegador durante o login. |
ux_mode |
string |
O modo de UX a ser usado no fluxo de login. Por padrão, o fluxo de consentimento é aberto em um pop-up. Os valores válidos são: popup e redirect . |
redirect_uri |
string |
Se você usa ux_mode='redirect' , esse parâmetro permite substituir o redirect_uri padrão que será usado ao 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. Define se as
permissões
granulares serão ativadas. 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. Nenhum efeito para os IDs do cliente OAuth criados durante ou depois de 2019, 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 antiga biblioteca do Google Platform.
Por padrão, os IDs do cliente recém-criados agora não podem mais usar a biblioteca do Platform e, em vez disso, precisam utilizar 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 a 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 os métodos de 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 ele estiver desconectado ou o objeto GoogleAuth não tiver sido 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() 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 preenchida 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 os códigos de erro na próxima seção. |
Códigos de erro
Consulte os GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Faz o login do usuário usando as opções especificadas.
Argumentos | |
---|---|
options |
Possibilidades:
|
Retorna | |
---|---|
Promise | Uma Promise preenchida 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 tiver ocorrido um erro (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çãoprompt: 'none'
. Essa opção não é obrigatória, porquegapi.auth2.init
fará o login automático do usuário se ele tiver feito login em uma sessão anterior.
gapi.auth2.SignInOptions
Interface que representa os diferentes parâmetros de configuração para o
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:
|
scope |
string |
Os escopos a serem solicitados, como uma string delimitada por espaços, sobre os escopos definidos nos parâmetros gapi.auth2.init . Essa propriedade é opcional quando fetch_basic_profile não está definido como falso.
|
ux_mode |
string |
O modo de UX a ser usado no fluxo de login. Por padrão, o fluxo de consentimento é aberto 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 permitirá substituir
o redirect_uri padrão que será usado ao 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.
Retorna | |
---|---|
Promise | Uma Promise que é preenchida quando o usuário é desconectado. |
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 objeto gapi.auth2.OfflineAccessOptions
que contém pares de chave-valor de parâmetros. Por exemplo: { scope: 'profile email' } |
Retorna | |
---|---|
Promise | Uma Promise que é atendida quando o usuário concede os escopos solicitados, transmitindo um objeto com o código de autorização para o gerenciador de fulfillment 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 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 solicitar o fluxo de consentimento. Erro gerado ao usar
signIn
com a opçãoprompt: 'none'
. Essa opção não é obrigatória para usar, já quegapi.auth2.init
fará o login automático do usuário se ele tiver feito login em uma sessão anterior.
gapi.auth2.OfflineAccessOptions
Interface que representa os diferentes parâmetros de configuração para o
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:
|
scope |
string |
Os escopos a serem solicitados, como uma string delimitada por espaços, sobre os escopos definidos nos parâmetros gapi.auth2.init . Essa propriedade é opcional quando fetch_basic_profile não está 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 o gerenciador de cliques será anexado. |
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.
Os objetos GoogleUser
normalmente são recebidos 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 GoogleAuth.then()
para receber uma instância 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 uma instância de GoogleUser
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 |
Você pode recuperar as propriedades de gapi.auth2.BasicProfile
com os seguintes métodos:
|
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 será retornado 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 outro escopo é 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 recarregado ao recarregar o
token OAuth.
|
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 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 conferir a lista de
parâmetros e o código de erro.
GoogleUser.grantofflineAccess(options)
Conseguir 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 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. Por exemplo:
{ scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }É possível especificar as seguintes opções:
|
Avançada
gapi.auth2.authorized(params, callback)
Executa uma autorização única do OAuth 2.0. 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 usuário do YouTube na primeira vez que ele fizer login.
- Seu aplicativo tem a própria infraestrutura de gerenciamento de sessão e requer o token de ID apenas 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 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 obrigatório do Google, por exemplo, devido a um ambiente
sem suporte. 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 solicitar o fluxo de consentimento. Erro gerado ao usar
signIn
com a opçãoprompt: '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 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' . Os valores
possíveis são:
|
prompt |
string |
Força um modo específico para o fluxo de consentimento. Os valores possíveis são:
|
cookie_policy |
string |
Os domínios para os quais os cookies de login serão criados. Um URI, single_host_origin ou none . Se não for especificado, o padrão será single_host_origin .
|
hosted_domain |
string |
O domínio do G Suite em que os usuários precisam pertencer a um usuário para fazer login. Ele é suscetível a ser modificado 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 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 anteriormente concedidos pelo usuário
ao app ou apenas os escopos solicitados na chamada atual. O valor padrão é true .
|
enable_granular_consent |
boolean |
Opcional. Define se as
permissões
granulares serão ativadas. 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. Nenhum efeito para os IDs do cliente OAuth criados durante ou depois de 2019, já que
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 a
biblioteca do Google Platform. Por padrão, os IDs de cliente recém-criados são impedidos de usar a biblioteca do Platform e, em vez disso, precisam utilizar 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 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 concedido. Presente apenas se permission ou token tiver sido especificado em response_type .
|
id_token |
string |
O token de ID concedido. Presente apenas se id_token tiver sido especificado em
response_type .
|
code |
string |
O código de autorização concedido. Presente apenas se code tiver sido especificado em
response_type .
|
scope |
string |
Os escopos concedidos no token de acesso. Presente apenas se permission ou token tiver sido especificado em response_type .
|
expires_in |
number |
O número de segundos até o token de acesso expirar. Presente apenas se permission
ou token tiver sido 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 tiver sido especificado em response_type .
|
expires_at |
number |
O carimbo de data/hora em que o token de acesso expira. Presente apenas se permission
ou token tiver sido especificado em response_type .
|
error |
string |
Quando a solicitação falhou, ele contém o código do erro. |
error_subtype |
string |
Quando há falha na solicitação, outras informações podem ser incluídas no código do erro retornado. |