Esta página foi traduzida pela API Cloud Translation.
Switch to English

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 qualquer problema ao usar a biblioteca, informe 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 de 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. Então, se o usuário já tiver feito login, o objeto GoogleAuth restaura o estado de login do usuário na 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 é 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 sem suporte), a função onError será chamada em seu lugar.

Argumentos
onInit A função chamada com o objeto GoogleAuth quando é totalmente inicializada.
onError A função chamada com um objeto que contém uma propriedade de error , se GoogleAuth falhar ao 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 é 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 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 aplicativo, encontrado e criado no Google Developers Console.
cookie_policy string Os domínios para os quais criar cookies de login. 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 definido como falso.
fetch_basic_profile boolean Busque as informações básicas de perfil dos usuários quando eles entrarem. 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 devem pertencer para fazer login. É suscetível a modificações por parte dos 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.
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 - popup e redirect .
redirect_uri string Se estiver usando ux_mode='redirect' , este parâmetro permite 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 hash.

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 usuário do Google, 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 este método.

Devoluções
gapi.auth2.GoogleAuth O objeto gapi.auth2.GoogleAuth . Use este objeto para chamar os métodos de 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 GoogleAuth 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 login do usuário atual.

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

GoogleAuth.signIn ()

gapi.auth2.init() 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 com sucesso os escopos solicitados ou rejeitada com um objeto contendo uma propriedade de error se um erro acontecer (veja abaixo os códigos de erro).

Códigos de erro

Veja GoogleAuth.signIn( options ) .

GoogleAuth.signIn ( options )

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

Argumentos
options Qualquer:
  • Um objeto gapi.auth2.SignInOptions contendo pares de valores-chave 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');
Devoluções
Promessa Uma Promise que é cumprida com a instância GoogleUser quando o usuário autentica e concede com sucesso os escopos solicitados, ou rejeitada com um objeto contendo uma propriedade de error se um erro acontecer (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' opção prompt: 'none' . O uso desta opção não deve ser obrigatório, pois gapi.auth2.init automaticamente o usuário se ele tiver feito login 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
    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 com várias contas selecione entre as várias contas para as quais ele 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 previamente com os escopos solicitados.
    Como gapi.auth2.init automaticamente um usuário ao aplicativo se ele já tiver feito login, a chamada de signIn({prompt: 'none'}) geralmente falhará.
scope string Os escopos a serem solicitados, como uma string delimitada por espaço, além dos escopos definidos nos parâmetros gapi.auth2.init . Opcional se fetch_basic_profile não estiver definido como falso.
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 - popup e redirect .
redirect_uri string Se estiver usando ux_mode='redirect' , este parâmetro permite 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 hash.

GoogleAuth.signOut ()

Sai da conta corrente 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 chave-valor de parâmetros. Por exemplo:
{
  scope: 'profile email'
}
Devoluções
Promessa Uma Promise que é cumprida quando o usuário concede os escopos solicitados, passando um objeto que contém 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' opção prompt: 'none' . Esta opção não deve ser exigida para uso, pois gapi.auth2.init fará o login automático do usuário se ele tiver feito login anteriormente durante 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
    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 com várias contas selecione entre as várias contas para as quais ele pode ter sessões atuais.
scope string Os escopos a serem solicitados, como uma string delimitada por espaço, além dos escopos definidos nos 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 manipulador de cliques do contêiner especificado.

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

Comercial

Um objeto GoogleUser representa uma conta de usuário. GoogleUser 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 inicializada do GoogleAuth .

Devoluções
GoogleUser O usuário atual

GoogleAuth.currentUser.listen ( listener )

Ouça as mudanças em currentUser.

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

GoogleUser.getId ()

Obtenha a string de ID exclusiva do usuário.

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 fez 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.

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 sempre deve 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.
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 é feita.

gapi.auth2.AuthResponse

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

Propriedades
access_token string O token de acesso concedido.
id_token string O token de identificação 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 pela primeira vez os escopos solicitados.
expires_at number O carimbo de data / hora em que o token de acesso irá expirar.

GoogleUser.hasGrantedScopes ( scopes )

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

Argumentos
scopes Uma string 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 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 IU

gapi.signin2.render ( id , options )

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

Argumentos
id O ID do elemento no qual processar o botão de login.
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
alcance Os escopos a serem solicitados quando o usuário faz 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 Exibe rótulos longos como "Sign in with Google" em vez de "Sign in" (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 ).
sucesso A função de retorno de chamada a ser chamada quando um usuário faz login com êxito. Essa função deve ter um argumento: uma instância de gapi.auth2.GoogleUser (padrão: nenhum).
falha 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

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 de 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 token de ID apenas uma vez para identificar o usuário em seu back-end.
  • Vários IDs de cliente são usados ​​na mesma página.
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 sem suporte. Uma propriedade 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' 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 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 tipos de resposta delimitados 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 com várias contas selecione entre as várias contas para as quais ele 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 previamente com os escopos solicitados.
    Se o code for solicitado como tipo de resposta, o código retornado só poderá ser trocado por um access_token , não um refresh_token .
cookie_policy string Os domínios para os quais criar cookies de login. 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. É suscetível a modificações por parte dos 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 para pré-selecionar no fluxo de login. Isso é suscetível a modificações pelo usuário, a menos que o prompt: "none" seja usado.
include_granted_scopes boolean Se deve solicitar um token de acesso que inclui todos os escopos anteriormente concedidos pelo usuário ao aplicativo ou apenas os escopos solicitados na chamada atual. O padrão é true .

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 a permission ou token foi especificado no response_type .
id_token string O token de identificação 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 a 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 a permission ou token foi especificado no response_type .
first_issued_at number O carimbo de data / hora em que o usuário concedeu pela primeira vez os escopos solicitados. Presente apenas se a permission ou token foi especificado no response_type .
expires_at number O carimbo de data / hora em que o token de acesso irá expirar. Presente apenas se a permission ou token foi especificado no response_type .
error string Quando a solicitação falhou, ele contém o código de erro .
error_subtype string Quando a solicitação falha, pode conter informações adicionais ao código de erro também retornado.