В этом справочнике описаны методы и атрибуты клиента 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 | Или:
|
Возврат | |
---|---|
Обещать | Promise , которое выполняется с экземпляром GoogleUser , когда пользователь успешно проходит аутентификацию и предоставляет запрошенные области, или отклоняется с помощью объекта, содержащего свойство error , если произошла ошибка (коды ошибок см. ниже). |
Коды ошибок
-
popup_closed_by_user
- Пользователь закрыл всплывающее окно, прежде чем завершить вход в систему.
-
access_denied
- Пользователь отклонил разрешение на необходимые области.
-
immediate_failed
- Ни один пользователь не может быть выбран автоматически без запроса потока согласия. Ошибка возникает при использовании
signIn
с опциейprompt: 'none'
. Эту опцию не следует использовать, такgapi.auth2.init
автоматически войдет в систему пользователя, если он ранее вошел в систему во время предыдущего сеанса.
разрыв.auth2.SignInOptions
Интерфейс, представляющий различные параметры конфигурации для метода GoogleAuth.signIn( options )
.
Параметры | ||
---|---|---|
prompt | string | Устанавливает определенный режим для потока согласия. Необязательный. Возможные значения:
|
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 | Устанавливает определенный режим для потока согласия. Необязательный. Возможные значения:
|
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 следующими методами:
|
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 }Вы можете указать следующие параметры:
|
Передовой
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' . Возможные значения:
|
prompt | string | Устанавливает определенный режим для потока согласия. Возможные значения:
|
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 | Если запрос не выполнен, он может содержать дополнительную информацию о коде ошибки, который также возвращается. |