Мы прекращаем поддержку библиотеки платформы JavaScript для входа в Google для веб-сайтов . Библиотека будет недоступна для загрузки после даты устаревания 31 марта 2023 г. Вместо этого используйте новые Google Identity Services для Интернета .
По умолчанию для вновь созданных идентификаторов клиентов теперь заблокировано использование старой библиотеки платформы, существующие идентификаторы клиентов не затрагиваются. Для новых идентификаторов клиентов, созданных до 29 июля 2022 года, можно установить `plugin_name` , чтобы включить использование библиотеки платформы Google.

Справочник по клиенту 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 */
  });
}

gapi.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 Developers Console.
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, запрашивать дополнительные области действия и выходить из текущей учетной записи.

gapi.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 автоматически войдет в систему пользователя, если он ранее входил в систему во время предыдущего сеанса.

gapi.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.отключить()

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

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 автоматически войдет в систему пользователя, если он ранее входил в систему во время предыдущего сеанса.

gapi.auth2.OfflineAccessOptions

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

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

onsuccess ( container , options , при успехе, 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, если пользователь вошел в систему.

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

GoogleUser.getHostedDomain()

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

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

GoogleUser.getGrantedScopes()

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

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

GoogleUser.getBasicProfile()

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

Возвращает
gapi.auth2.BasicProfile Вы можете получить свойства gapi.auth2.BasicProfile следующими методами:
  • Базовый профиль.getId()
  • Базовый профиль.getName()
  • BasicProfile.getGivenName()
  • BasicProfile.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, выполнено.

gapi.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 Отметка времени, по истечении которой токен доступа истечет.

scopes (области)

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

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

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

gapi.auth2.AuthorizeConfig

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

Характеристики
client_id string Требуется . Идентификатор клиента приложения, найденный и созданный в Google Developers Console.
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'

gapi.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 Если запрос не удался, он может содержать дополнительную информацию к возвращаемому коду ошибки.