Справочник по клиенту JavaScript для входа в Google

В этом справочнике описаны методы и атрибуты клиента JavaScript, которые вы будете использовать для реализации входа в Google в своих веб-приложениях.

Если у вас возникнут какие-либо проблемы с использованием библиотеки, сообщите об этом в наш репозиторий GitHub .

Настройка аутентификации

Загрузите библиотеку платформы API Google, чтобы создать объект gapi :

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

После загрузки библиотеки платформы загрузите библиотеку auth2 :

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

разрыв.auth2.init( params )

Инициализирует объект GoogleAuth . Вы должны вызвать этот метод перед вызовом gapi.auth2.GoogleAuth .

При инициализации объекта GoogleAuth вы настраиваете для него свой идентификатор клиента OAuth 2.0 и любые дополнительные параметры, которые хотите указать. Затем, если пользователь уже вошел в систему, объект GoogleAuth восстанавливает состояние входа пользователя из предыдущего сеанса.

Аргументы
params Объект, содержащий пары ключ-значение данных конфигурации клиента. gapi.auth2.ClientConfig для получения информации о различных настраиваемых свойствах. Например:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Возврат
gapi.auth2.GoogleAuth gapi.auth2.GoogleAuth . Используйте метод then() , чтобы получить обещание, которое будет выполнено, когда gapi.auth2.GoogleAuth завершит инициализацию.

GoogleAuth.then( onInit , onError )

Вызывает функцию onInit , когда объект GoogleAuth полностью инициализирован. Если при инициализации возникает ошибка (это может произойти в старых неподдерживаемых браузерах), вместо этого будет вызвана функция onError .

Аргументы
onInit Функция, вызываемая с объектом GoogleAuth , когда он полностью инициализирован.
onError Функция, вызываемая с объектом, содержащим свойство error , если GoogleAuth не удалось инициализировать.
Возврат
Обещать Promise , которое выполняется после завершения функции onInit или отклоняется, если возникла ошибка инициализации. Он разрешается с использованием значения, возвращаемого функцией onInit , если таковое имеется.

Коды ошибок

idpiframe_initialization_failed
Не удалось инициализировать необходимый iframe от Google, например, из-за неподдерживаемой среды. Свойство details предоставит дополнительную информацию о возникшей ошибке.

gapi.auth2.ClientConfig

Интерфейс, представляющий различные параметры конфигурации для gapi.auth2.init .

Параметры
client_id string Необходимый. Идентификатор клиента приложения, найденный и созданный в консоли разработчиков Google.
cookie_policy string Домены, для которых создаются файлы cookie для входа. Либо URI, single_host_origin , либо none . По умолчанию используется single_host_origin , если не указано.
scope string Запрашиваемые области в виде строки, разделенной пробелами. Необязательно, если для fetch_basic_profile не установлено значение false.
fetch_basic_profile boolean Получает базовую информацию профиля пользователя при входе в систему. Добавляет «профиль», «электронную почту» и «openid» в запрошенные области. Верно, если не указано.
hosted_domain string Домен G Suite, к которому должны принадлежать пользователи для входа. Он может быть изменен клиентами, поэтому обязательно проверьте свойство размещенного домена возвращенного пользователя. Используйте GoogleUser.getHostedDomain() на клиенте и утверждение hd в идентификаторе токена на сервере, чтобы убедиться, что домен соответствует вашим ожиданиям.
ux_mode string Режим UX, используемый для процесса входа. По умолчанию поток согласия откроется во всплывающем окне. Допустимые значения: popup и redirect .
redirect_uri string При использовании ux_mode='redirect' этот параметр позволяет переопределить redirect_uri по умолчанию, который будет использоваться в конце потока согласия. По умолчанию redirect_uri — это текущий URL-адрес, лишенный параметров запроса и фрагмента хэша.
plugin_name string Необязательный. Если это значение установлено, новые идентификаторы клиентов, созданные до 29 июля 2022 г., могут использовать старую библиотеку платформы Google. По умолчанию вновь созданным идентификаторам клиентов теперь запрещено использовать библиотеку платформы, и вместо этого они должны использовать более новую библиотеку Google Identity Services. Вы можете выбрать любое значение, для облегчения идентификации рекомендуется использовать описательное имя, например название продукта или плагина. Пример: plugin_name: 'YOUR_STRING_HERE'

Аутентификация

GoogleAuth — это одноэлементный класс, который предоставляет методы, позволяющие пользователю войти в систему с учетной записью Google, получить текущий статус входа пользователя, получить определенные данные из профиля Google пользователя, запросить дополнительные области и выйти из текущей учетной записи.

разрыв.auth2.getAuthInstance()

Возвращает объект GoogleAuth . Перед вызовом этого метода необходимо инициализировать объект GoogleAuth с помощью gapi.auth2.init() .

Возврат
gapi.auth2.GoogleAuth gapi.auth2.GoogleAuth . Используйте этот объект для вызова gapi.auth2.GoogleAuth .

GoogleAuth.isSignedIn.get()

Возвращает, вошел ли текущий пользователь в систему.

Возврат
логическое значение true если пользователь вошел в систему, или false , если пользователь вышел из системы или объект GoogleAuth не инициализирован.

GoogleAuth.isSignedIn.listen(прослушиватель)

Прослушивайте изменения в состоянии входа текущего пользователя.

Аргументы
listener Функция, принимающая логическое значение. listen() передает этой функции true , когда пользователь входит в систему, и false , когда пользователь выходит из системы.

GoogleAuth.signIn()

Выполняет вход пользователя с параметрами, указанными gapi.auth2.init() .

Возврат
Обещать Promise , которое выполняется с экземпляром GoogleUser , когда пользователь успешно проходит аутентификацию и предоставляет запрошенные области, или отклоняется с помощью объекта, содержащего свойство error , если произошла ошибка (коды ошибок см. ниже).

Коды ошибок

См. GoogleAuth.signIn( options ) .

GoogleAuth.signIn( options )

Выполняет вход пользователя, используя указанные параметры.

Аргументы
options Или:
  • gapi.auth2.SignInOptions , содержащий пары «ключ-значение» параметров входа. Например:
    {
      scope: 'profile email'
    }
  • gapi.auth2.SigninOptionsBuilder . Например:
    options = new gapi.auth2.SigninOptionsBuilder();
    options.setAppPackageName('com.example.app');
    options.setFetchBasicProfile(True);
    options.setPrompt('select_account');
    options.setScope('profile').setScope('email');
Возврат
Обещать Promise , которое выполняется с экземпляром GoogleUser , когда пользователь успешно проходит аутентификацию и предоставляет запрошенные области, или отклоняется с помощью объекта, содержащего свойство error , если произошла ошибка (коды ошибок см. ниже).

Коды ошибок

popup_closed_by_user
Пользователь закрыл всплывающее окно, прежде чем завершить вход в систему.
access_denied
Пользователь отклонил разрешение на необходимые области.
immediate_failed
Ни один пользователь не может быть выбран автоматически без запроса потока согласия. Ошибка возникает при использовании signIn с опцией prompt: 'none' . Эту опцию не следует использовать, так gapi.auth2.init автоматически войдет в систему пользователя, если он ранее вошел в систему во время предыдущего сеанса.

разрыв.auth2.SignInOptions

Интерфейс, представляющий различные параметры конфигурации для метода GoogleAuth.signIn( options ) .

Параметры
prompt string Устанавливает определенный режим для потока согласия. Необязательный.
Возможные значения:
  • consent
    Сервер авторизации запрашивает у пользователя согласие перед возвратом информации в приложение.
  • select_account
    Сервер авторизации предлагает пользователю выбрать учетную запись Google. Это позволяет пользователю, имеющему несколько учетных записей, выбирать среди нескольких учетных записей, для которых у него могут быть текущие сеансы.
  • none ( не рекомендуется )
    Сервер авторизации не будет отображать экраны аутентификации или согласия пользователя; он вернет ошибку, если пользователь еще не прошел аутентификацию и ранее не дал согласия на запрошенные области.
    gapi.auth2.init автоматически войдет в приложение пользователя, если он ранее вошел в систему, вызов signIn({prompt: 'none'}) обычно завершается неудачей.
scope string Запрашиваемые области в виде строки, разделенной пробелами, поверх областей, определенных в gapi.auth2.init . Необязательно, если для fetch_basic_profile не установлено значение false.
ux_mode string Режим UX, используемый для процесса входа. По умолчанию поток согласия откроется во всплывающем окне. Допустимые значения: popup и redirect .
redirect_uri string При использовании ux_mode='redirect' этот параметр позволяет переопределить redirect_uri по умолчанию, который будет использоваться в конце потока согласия. По умолчанию redirect_uri — это текущий URL-адрес, лишенный параметров запроса и фрагмента хэша.

GoogleAuth.signOut()

Выход из текущего аккаунта из приложения.

Возврат
Обещать Promise , которое выполняется, когда пользователь вышел из системы.

GoogleAuth.disconnect()

Отменяет все области, предоставленные пользователем.

GoogleAuth.grantOfflineAccess ( options )

Получите от пользователя разрешение на доступ к указанным областям в автономном режиме.

Аргументы
options gapi.auth2.OfflineAccessOptions , содержащий пары параметров «ключ-значение». Например:
{
  scope: 'profile email'
}
Возврат
Обещать Promise , которое выполняется, когда пользователь предоставляет запрошенные области, передавая объект, содержащий код авторизации, обработчику выполнения Promise . Например:
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Коды ошибок

popup_closed_by_user
Пользователь закрыл всплывающее окно до завершения потока согласия.
access_denied
Пользователь отклонил разрешение на необходимые области.
immediate_failed
Ни один пользователь не может быть выбран автоматически без запроса потока согласия. Ошибка возникает при использовании signIn с опцией prompt: 'none' . Эту опцию не следует использовать, так gapi.auth2.init автоматически войдет в систему пользователя, если он ранее вошел в систему во время предыдущего сеанса.

разрыв.auth2.OfflineAccessOptions

Интерфейс, представляющий различные параметры конфигурации для метода GoogleAuth.grantOfflineAccess( options ) .

Параметры
prompt string Устанавливает определенный режим для потока согласия. Необязательный.
Возможные значения:
  • consent
    Сервер авторизации запрашивает у пользователя согласие перед возвратом информации в приложение.
  • select_account
    Сервер авторизации предлагает пользователю выбрать учетную запись Google. Это позволяет пользователю, имеющему несколько учетных записей, выбирать среди нескольких учетных записей, для которых у него могут быть текущие сеансы.
scope string Запрашиваемые области в виде строки, разделенной пробелами, поверх областей, определенных в gapi.auth2.init . Необязательно, если для fetch_basic_profile не установлено значение false.

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

Прикрепляет поток входа к обработчику кликов указанного контейнера.

Аргументы
container Идентификатор или ссылка на элемент div , к которому можно прикрепить обработчик кликов.
options Объект, содержащий пары параметров «ключ-значение». См. GoogleAuth.signIn() .
onsuccess Функция, вызываемая после завершения входа.
onfailure Функция, вызываемая в случае сбоя входа в систему.

Пользователи

Объект GoogleUser представляет одну учетную запись пользователя. Объекты GoogleUser обычно получаются путем вызова GoogleAuth.currentUser.get() .

GoogleAuth.currentUser.get()

Возвращает объект GoogleUser , представляющий текущего пользователя. Обратите внимание, что в только что инициализированном экземпляре GoogleAuth текущий пользователь не установлен. Используйте метод currentUser.listen() или GoogleAuth.then() , чтобы получить инициализированный экземпляр GoogleAuth .

Возврат
GoogleUser Текущий пользователь

GoogleAuth.currentUser.listen( listener )

Прослушивайте изменения в currentUser.

Аргументы
listener Функция, принимающая параметр GoogleUser . listen передает этой функции экземпляр GoogleUser при каждом изменении, изменяющем currentUser .

GoogleUser.getId()

Получите уникальную строку идентификатора пользователя.

Возврат
Нить Уникальный идентификатор пользователя

GoogleUser.isSignedIn()

Возвращает true, если пользователь вошел в систему.

Возврат
логическое значение True, если пользователь вошел в систему

GoogleUser.getHostedDomain()

Получите домен G Suite пользователя, если пользователь вошел в систему с учетной записью G Suite.

Возврат
Нить Домен G Suite пользователя

GoogleUser.getGrantedScopes()

Получите области, предоставленные пользователем, в виде строки, разделенной пробелами.

Возврат
Нить Области действия, предоставленные пользователем

GoogleUser.getBasicProfile()

Получите основную информацию о профиле пользователя.

Возврат
gapi.auth2.BasicProfile Вы можете получить gapi.auth2.BasicProfile следующими методами:
  • БазовыйПрофиль.getId()
  • БазовыйПрофиль.getName()
  • БазовыйПрофиле.getGivenName()
  • БазовыйПрофиль.getFamilyName()
  • БазовыйПрофиле.getImageUrl()
  • БазовыйПрофиль.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

Получите объект ответа из сеанса аутентификации пользователя.

Аргументы
includeAuthorizationData Необязательно: логическое значение, указывающее, всегда ли возвращать токен доступа и области. По умолчанию токен доступа и запрошенные области не возвращаются, если fetch_basic_profile имеет значение true (значение по умолчанию) и дополнительные области не запрашиваются.
Возврат
gapi.auth2.AuthResponse gapi.auth2.AuthResponse .

GoogleUser.reloadAuthResponse()

Принудительно обновляет токен доступа, а затем возвращает обещание для нового ответа AuthResponse.

Возврат
Promise Promise , которое выполняется с помощью перезагруженного gapi.auth2.AuthResponse при перезагрузке токена OAuth, выполнено.

разрыв.auth2.AuthResponse

Ответ возвращается при вызове методов GoogleUser.getAuthResponse( includeAuthorizationData ) или GoogleUser.reloadAuthResponse() .

Характеристики
access_token string Токен доступа предоставлен.
id_token string Идентификационный токен предоставлен.
scope string Области, предоставленные в маркере доступа.
expires_in number Количество секунд до истечения срока действия токена доступа.
first_issued_at number Отметка времени, когда пользователь впервые предоставил запрошенные области.
expires_at number Временная метка истечения срока действия токена доступа.

GoogleUser.hasGrantedScopes( scopes )

Возвращает true, если пользователь предоставил указанные области.

Аргументы
scopes Строка областей, разделенная пробелами.
Возврат
логическое значение Истинно, если области были предоставлены

GoogleUser.grant( options )

Запросить дополнительные области для пользователя.

См. GoogleAuth.signIn() для получения списка параметров и кода ошибки.

GoogleUser.grantOfflineAccess( options )

Получите от пользователя разрешение на доступ к указанным областям в автономном режиме.

Аргументы
options gapi.auth2.OfflineAccessOptions , содержащий пары параметров «ключ-значение». Например:
{
  scope: 'profile email'
}

GoogleUser.disconnect()

Отменяет все области, предоставленные пользователем приложению.

элементы пользовательского интерфейса

gapi.signin2.render( id , options )

Отображает кнопку входа в элементе с заданным идентификатором, используя настройки, заданные объектом options .

Аргументы
id Идентификатор элемента, в котором отображается кнопка входа.
options Объект, содержащий настройки, используемые для визуализации кнопки. Например:
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
Вы можете указать следующие параметры:
Параметры
объем Области, запрашиваемые при входе пользователя в систему (по умолчанию: profile ).
ширина Ширина кнопки в пикселях (по умолчанию: 120 ).
высота Высота кнопки в пикселях (по умолчанию: 36 ).
длинное название Отображать длинные метки, например «Войти через Google», а не «Войти» (по умолчанию: false ). Когда вы используете длинные заголовки, вам следует увеличить ширину кнопки по сравнению с ее шириной по умолчанию.
тема Цветовая тема кнопки: light или dark (по умолчанию: light ).
успех Функция обратного вызова, вызываемая при успешном входе пользователя в систему. Эта функция должна принимать один аргумент: экземпляр gapi.auth2.GoogleUser (по умолчанию: нет).
при отказе Функция обратного вызова, вызываемая при сбое входа. Эта функция не принимает аргументов (по умолчанию: нет).

Передовой

gapi.auth2.authorize( params , callback )

Выполняет однократную авторизацию OAuth 2.0. В зависимости от используемых параметров откроется всплывающее окно для входа в систему Google или будет предпринята попытка загрузить запрошенный ответ автоматически, без взаимодействия с пользователем.

Некоторые случаи использования, где этот метод полезен, включают:

  • Вашему приложению достаточно один раз запросить конечную точку API Google, например, чтобы загрузить любимые видео пользователя на YouTube при первом входе в систему.
  • Ваше приложение имеет собственную инфраструктуру управления сеансами, и токен идентификатора требуется только один раз для идентификации пользователя в вашем серверном интерфейсе.
  • На одной странице используются несколько идентификаторов клиента.
Аргументы
params Объект, содержащий пары ключ-значение данных конфигурации. gapi.auth2.AuthorizeConfig для получения информации о различных настраиваемых свойствах. Например:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback Функция, вызываемая с помощью gapi.auth2.AuthorizeResponse после завершения запроса (успешного или с ошибкой).

Пример

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.
});

Коды ошибок

idpiframe_initialization_failed
Не удалось инициализировать необходимый iframe от Google, например, из-за неподдерживаемой среды. Свойство details предоставит дополнительную информацию о возникшей ошибке.
popup_closed_by_user
Пользователь закрыл всплывающее окно, прежде чем завершить вход в систему.
access_denied
Пользователь отклонил разрешение на необходимые области.
immediate_failed
Ни один пользователь не может быть выбран автоматически без запроса потока согласия. Ошибка возникает при использовании signIn с опцией prompt: 'none' .

разрыв.auth2.AuthorizeConfig

Интерфейс, представляющий различные параметры конфигурации для gapi.auth2.authorize .

Характеристики
client_id string Необходимый . Идентификатор клиента приложения, найденный и созданный в консоли разработчиков Google.
scope string Необходимый . Запрашиваемые области в виде строки, разделенной пробелами.
response_type string Список типов ответов, разделенных пробелами. По умолчанию 'permission' . Возможные значения:
  • id_token , чтобы получить токен идентификатора
  • permission (или token ) для получения токена доступа
  • code , чтобы получить код авторизации
prompt string Устанавливает определенный режим для потока согласия. Возможные значения:
  • consent
    Сервер авторизации запрашивает у пользователя согласие перед возвратом информации в приложение.
  • select_account
    Сервер авторизации предлагает пользователю выбрать учетную запись Google. Это позволяет пользователю, имеющему несколько учетных записей, выбирать среди нескольких учетных записей, для которых у него могут быть текущие сеансы.
  • none
    Сервер авторизации не будет отображать экраны аутентификации или согласия пользователя; он вернет ошибку, если пользователь еще не прошел аутентификацию и ранее не дал согласия на запрошенные области.
    Если в качестве типа ответа запрашивается code , возвращаемый код можно будет обменять только на access_token , а не refresh_token .
cookie_policy string Домены, для которых создаются файлы cookie для входа. Либо URI, single_host_origin , либо none . По умолчанию используется single_host_origin , если не указано.
hosted_domain string Домен G Suite, к которому должны принадлежать пользователи для входа. Он может быть изменен клиентами, поэтому обязательно проверьте свойство размещенного домена возвращенного пользователя.
login_hint string Адрес электронной почты или идентификатор пользователя, которого нужно предварительно выбрать в процессе входа. Это может быть изменено пользователем, если не используется prompt: "none" .
include_granted_scopes boolean Следует ли запрашивать токен доступа, включающий все области, ранее предоставленные пользователем приложению, или только области, запрошенные в текущем вызове. По умолчанию true .
plugin_name string Необязательный. Если этот параметр установлен, идентификаторы клиентов, созданные до 29 июля 2022 г., могут использовать библиотеку платформы Google. По умолчанию вновь созданным идентификаторам клиентов запрещено использовать библиотеку платформы, и вместо этого они должны использовать более новую библиотеку Google Identity Services. Вы можете выбрать любое значение, для облегчения идентификации рекомендуется использовать описательное имя, например название продукта или плагина. Пример: plugin_name: 'YOUR_STRING_HERE'

разрыв.auth2.AuthorizeResponse

Ответ вернулся в обратный вызов gapi.auth2.authorize .

Характеристики
access_token string Токен доступа предоставлен. Присутствует только в том случае, если permission или token были указаны в response_type .
id_token string Идентификационный токен предоставлен. Присутствует только в том случае, если id_token был указан в response_type .
code string Код авторизации предоставлен. Присутствует только в том случае, если code был указан в response_type .
scope string Области, предоставленные в маркере доступа. Присутствует только в том случае, если permission или token были указаны в response_type .
expires_in number Количество секунд до истечения срока действия токена доступа. Присутствует только в том случае, если permission или token были указаны в response_type .
first_issued_at number Отметка времени, когда пользователь впервые предоставил запрошенные области. Присутствует только в том случае, если permission или token были указаны в response_type .
expires_at number Временная метка истечения срока действия токена доступа. Присутствует только в том случае, если permission или token были указаны в response_type .
error string Если запрос не выполнен, он содержит код ошибки .
error_subtype string Если запрос не выполнен, он может содержать дополнительную информацию о коде ошибки, который также возвращается.