Справочник по JavaScript API для функции "Войти с аккаунтом Google"

На этой странице описан JavaScript API функции "Войти с аккаунтом Google", который используется для показа кнопки "Войти с аккаунтом Google" или всплывающего окна One Tap на веб-страницах.

Метод: google.accounts.id.initialize

Метод google.accounts.id.initialize инициализирует клиент функции "Войти с аккаунтом Google" на основе объекта конфигурации. Пример кода:

google.accounts.id.initialize(IdConfiguration)

В следующем примере кода метод google.accounts.id.initialize реализуется с помощью функции onload:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

Метод google.accounts.id.initialize создает экземпляр клиента функции "Войти с аккаунтом Google", который может неявно использоваться всеми модулями на той же веб-странице.

• Метод google.accounts.id.initialize нужно вызвать только один раз, даже если вы используете несколько модулей (например, вход в одно касание, персонализированную кнопку, отзыв и т. д.) на одной веб-странице.
• Если вы вызовете метод google.accounts.id.initialize несколько раз, будут сохранены и использованы только конфигурации из последнего вызова.

Вы сбрасываете конфигурации при каждом вызове метода google.accounts.id.initialize, и все последующие методы на той же веб-странице сразу же используют новые конфигурации.

Тип данных: IdConfiguration.

В таблице ниже перечислены поля и описания типа данных IdConfiguration.

client_id

Это поле содержит идентификатор клиента вашего приложения, который можно найти и создать в консоли Google Cloud. Подробная информация приведена в таблице ниже.

color_scheme

Цветовая схема, которая применяется к подсказке One Tap. Подробная информация приведена в таблице ниже.

В таблице ниже перечислены доступные цветовые схемы и их описания.

auto_select

Это поле определяет, будет ли токен идентификатора автоматически возвращаться без взаимодействия с пользователем, если есть только один сеанс Google, который ранее одобрил ваше приложение. Значение по умолчанию: false. Дополнительную информацию можно найти в таблице ниже.

обратный вызов

Это поле представляет собой функцию JavaScript, которая обрабатывает токен идентификатора, возвращенный из подсказки One Tap или всплывающего окна. Этот атрибут обязателен, если используется Google One Tap или кнопка "Войти с аккаунтом Google" в режиме UX popup. Подробная информация приведена в таблице ниже.

login_uri

Этот атрибут является URI конечной точки входа.

Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в консоли Google Cloud, и соответствовать нашим правилам проверки URI перенаправления.

Этот атрибут можно опустить, если текущая страница является страницей входа. В этом случае учетные данные по умолчанию отправляются на эту страницу.

Ответ с учетными данными токена идентификатора отправляется в конечную точку входа, когда пользователь нажимает кнопку "Войти с аккаунтом Google" и используется режим UX с перенаправлением.

Подробная информация приведена в таблице ниже.

Ваша конечная точка входа должна обрабатывать запросы POST, содержащие параметр credential со значением токена идентификатора в теле. select_by не включается в HTTP-запросы POST к login_uri или data-login_uri и возвращается только в объекте CredentialResponse, который передается функции JavaScript callback.

native_callback

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

cancel_on_tap_outside

Это поле определяет, следует ли отменять запрос One Tap, если пользователь нажимает за пределами подсказки. Значение по умолчанию: true. Чтобы отключить его, задайте значение false. Подробная информация приведена в таблице ниже.

prompt_parent_id

Этот атрибут задает идентификатор DOM элемента контейнера. Если он не задан, окно входа в одно касание будет показано в правом верхнем углу. Подробная информация приведена в таблице ниже.

nonce : однократно используемое число

Это поле представляет собой случайную строку, используемую токеном идентификатора для предотвращения атак повторного воспроизведения. Подробная информация приведена в таблице ниже.

Длина одноразового кода ограничена максимальным размером JWT, поддерживаемым вашей средой, а также ограничениями на размер HTTP-запросов в браузере и на сервере.

essential_claims

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

Подробная информация приведена в таблице ниже.

context

Это поле меняет текст заголовка и сообщений, которые показываются в подсказке One Tap. Оно не влияет на браузеры с ITP. Значение по умолчанию – signin.

Подробная информация приведена в таблице ниже.

В таблице ниже перечислены все доступные контексты и их описания.

state_cookie_domain

Если вам нужно показывать One Tap в родительском домене и его субдоменах, передайте родительский домен в это поле, чтобы использовался один файл cookie с общим состоянием. Подробная информация приведена в таблице ниже.

ux_mode

Используйте это поле, чтобы задать процесс UX, используемый кнопкой "Войти с аккаунтом Google". Значение по умолчанию – popup. Этот атрибут не влияет на OneTap UX. Подробная информация приведена в таблице ниже.

В таблице ниже перечислены доступные режимы UX и их описания.

allowed_parent_origin

Источники, которым разрешено встраивать промежуточный iframe. Если это поле присутствует, One Tap запускается в режиме промежуточного iframe. Дополнительную информацию можно найти в таблице ниже.

В таблице ниже перечислены поддерживаемые типы значений и их описания.

Также поддерживаются префиксы с подстановочными знаками. Например, "https://*.example.com" соответствует example.com и его субдоменам на всех уровнях (например, news.example.com, login.news.example.com). При использовании подстановочных знаков необходимо учитывать следующее:

• Строка шаблона не может состоять только из подстановочного знака и домена верхнего уровня. Например, https://.com и https://.co.uk недопустимы, поскольку "https://.example.com" соответствует example.com и всем его субдоменам. Чтобы указать два разных домена, используйте список, разделенный запятыми. Например, "https://example1.com,https://.example2.com" соответствует доменам example1.com, example2.com и субдоменам example2.com.
• Домены с подстановочными знаками должны начинаться с защищенной схемы https://, поэтому "*.example.com" считается недопустимым.

Если значение поля allowed_parent_origin недействительно, инициализация One Tap в режиме промежуточного iframe завершится ошибкой и будет остановлена.

intermediate_iframe_close_callback

Переопределяет стандартное поведение промежуточного окна iframe, когда пользователи вручную закрывают One Tap, нажимая кнопку "X" в интерфейсе One Tap. Режим работы по умолчанию — удаление промежуточного окна iframe из DOM сразу.

Поле intermediate_iframe_close_callback действует только в режиме промежуточного iframe. Это влияет только на промежуточный фрейм iframe, а не на фрейм iframe One Tap. Интерфейс One Tap удаляется до вызова обратного вызова.

itp_support

Это поле определяет, следует ли включить улучшенный интерфейс One Tap в браузерах, поддерживающих Intelligent Tracking Prevention (ITP). Значение по умолчанию – false. Дополнительную информацию можно найти в таблице ниже.

login_hint

Если ваше приложение заранее знает, какой пользователь должен войти в систему, оно может предоставить Google подсказку для входа. Если все пройдет успешно, выбор аккаунта будет пропущен. Допустимые значения: адрес электронной почты или значение поля sub токена идентификатора.

Дополнительную информацию можно найти в разделе, посвященном полю login_hint, в документации по OpenID Connect.

HD

Если у пользователя несколько аккаунтов, но он должен входить только с аккаунтом Workspace, используйте этот параметр, чтобы предоставить Google подсказку о доменном имени. В случае успеха при выборе аккаунта будут показываться только аккаунты из указанного домена. Подстановочное значение * предлагает пользователю только аккаунты Workspace и исключает обычные аккаунты (user@gmail.com) при выборе аккаунта.

Дополнительную информацию можно найти в разделе, посвященном полю hd в документации по OpenID Connect.

use_fedcm_for_prompt

Разрешите браузеру управлять предложениями войти в аккаунт и процессом входа между вашим сайтом и Google. Значение по умолчанию – false. Подробную информацию вы найдете на странице Переход на FedCM.

use_fedcm_for_button

Это поле определяет, следует ли использовать кнопку FedCM UX в Chrome (на компьютерах с M125 и более поздними версиями и на устройствах Android с M128 и более поздними версиями). Значение по умолчанию – false. Дополнительную информацию можно найти в таблице ниже.

button_auto_select

Это поле определяет, нужно ли включить параметр автоматического выбора для процесса кнопки FedCM. Если включить эту функцию, то вернувшиеся пользователи с активным сеансом Google будут автоматически входить в аккаунт без запроса на выбор аккаунта. Значение по умолчанию – false. Вам нужно включить автоматический вход по кнопке во время запуска. Подробная информация приведена в таблице ниже.

Метод: google.accounts.id.prompt

Метод google.accounts.id.prompt показывает окно входа в одно нажатие или встроенный менеджер учетных данных браузера после вызова метода initialize(). Пример кода:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

Обычно метод prompt() вызывается при загрузке страницы. Из-за статуса сеанса и настроек пользователя в Google интерфейс One Tap может не показываться. Чтобы получать уведомления о статусе интерфейса в разные моменты, передайте функцию.

Уведомления отправляются в следующих случаях:

• Момент показа. Показ происходит после вызова метода prompt(). Уведомление содержит логическое значение, указывающее, отображается ли интерфейс.

• Пропущенный момент. Это происходит, когда окно One Tap закрывается автоматически или вручную, а также когда Google не может выдать учетные данные, например если в выбранном сеансе выполнен выход из аккаунта Google.

  В таких случаях рекомендуем перейти к следующему поставщику идентификационной информации, если он есть.

• Момент закрытия. Наступает, когда Google успешно получает учетные данные или пользователь хочет остановить процесс их получения. Например, когда пользователь начинает вводить имя пользователя и пароль в диалоговом окне входа, вы можете вызвать метод google.accounts.id.cancel(), чтобы закрыть окно входа в одно нажатие и запустить момент отклонения.

В следующем примере кода реализован пропущенный момент:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

Тип данных: PromptMomentNotification

В таблице ниже перечислены методы и описания типа данных PromptMomentNotification.

Тип данных: CredentialResponse

При вызове функции callback в качестве параметра передается объект CredentialResponse. В таблице ниже перечислены поля, которые содержатся в объекте ответа на запрос учетных данных.

учетка

Это поле представляет собой токен идентификатора в виде строки веб-токена JSON (JWT) в кодировке Base64.

После декодирования токен JWT выглядит следующим образом:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

Поле sub – это глобальный уникальный идентификатор аккаунта Google. В качестве идентификатора пользователя используйте только поле sub, поскольку оно уникально для всех аккаунтов Google и никогда не используется повторно.

С помощью полей email, email_verified и hd можно определить, размещает ли Google адрес электронной почты и является ли он авторитетным для него. Если Google является авторитетным источником, пользователь подтверждается как законный владелец аккаунта.

Примеры, когда Google является авторитетным источником:

• email имеет суффикс @gmail.com, это аккаунт Gmail.
• Если email_verified имеет значение true и задано значение hd, это аккаунт Google Workspace.

Пользователи могут регистрировать аккаунты Google без использования Gmail или Google Workspace. Если email не содержит суффикс @gmail.com и hd отсутствует, Google не является авторитетным источником и для проверки пользователя рекомендуется использовать пароль или другие методы. Значение email_verfied также может быть истинным, поскольку Google изначально подтвердил пользователя при создании аккаунта Google, однако с тех пор право собственности на сторонний аккаунт электронной почты могло измениться.

В поле exp указано время, до которого вы должны проверить токен на стороне сервера. Для токена идентификации, полученного при входе с аккаунтом Google, этот срок составляет один час. Подтвердите токен до истечения срока его действия. Не используйте exp для управления сеансами. Истечение срока действия токена идентификации не означает, что пользователь вышел из аккаунта. Ваше приложение отвечает за управление сеансами пользователей.

select_by

В таблице ниже перечислены возможные значения поля select_by. Значение задается в зависимости от типа кнопки, сеанса и статуса согласия.

• Пользователь нажал кнопку One Tap или "Войти с аккаунтом Google" или использовал бесконтактный автоматический вход.

• Обнаружен существующий сеанс, или пользователь выбрал аккаунт Google и вошел в него, чтобы начать новый сеанс.

• Прежде чем передать приложению учетные данные токена идентификатора, пользователь должен:

  • нажал кнопку "Подтвердить", чтобы дать согласие на передачу учетных данных; или
  • ранее дал согласие и выбрал аккаунт Google в окне выбора аккаунта.

Значение в этом поле имеет один из следующих типов:

штат

Это поле заполняется, только если пользователь нажимает кнопку "Войти с аккаунтом Google" и для нее задан атрибут state. Значение этого поля совпадает со значением, указанным в атрибуте state кнопки.

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

Метод: google.accounts.id.renderButton

Метод google.accounts.id.renderButton добавляет на веб-страницы кнопку "Войти с аккаунтом Google".

Пример кода:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

Тип данных: GsiButtonConfiguration.

В таблице ниже перечислены поля и описания типа данных GsiButtonConfiguration.

Типы атрибутов

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

тип

Тип кнопки. Значение по умолчанию: standard.

Подробная информация приведена в таблице ниже.

В таблице ниже перечислены доступные типы кнопок и их описания.

Тип
standard
icon

тема

Тема кнопки. Значение по умолчанию: outline. Подробная информация приведена в таблице ниже.

В таблице ниже перечислены доступные темы и их описания.

Тема	Примеры	Характеристики
outline		Заливка: #FFFFFF Обводка: #747775 | 1px | внутри Шрифт: #1F1F1F | Roboto Medium | 14/20 Персонализированный: #1F1F1F | Roboto | Medium 12/14 | Regular 11/13
filled_blue		Заливка: #0B57D0 Обводка: #OB57D0 | 1 пкс | внутри Шрифт: #FFFFFF | Google Sans Medium | 14/20 Персонализированный: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
filled_black		Заливка: #202124 Обводка: #OB57D0 | 1px | внутри Шрифт: #FFFFFF | Google Sans Medium | 14/20 Персонализированный: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
outline_dark		Заливка: #131314 Обводка: #8E918F | 1px | внутри Шрифт: #FFFFFF | Google Sans Medium | 14/20 Персонализированный: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13

размер

Размер кнопки. Значение по умолчанию: large. Подробная информация приведена в таблице ниже.

В таблице ниже перечислены доступные размеры кнопок и их описания.

Размер
large
medium
small

Текст

Текст кнопки. Значение по умолчанию: signin_with. Текст кнопок со значками, у которых разные атрибуты text, визуально не отличается. Единственное исключение – когда текст читается для специальных возможностей экрана.

Подробная информация приведена в таблице ниже.

В таблице ниже перечислены все доступные варианты текста для кнопок и их описания.

Текст
signin_with
signup_with
continue_with
signin

shape

Форма кнопки. Значение по умолчанию: rectangular. Дополнительную информацию можно найти в таблице ниже.

В таблице ниже перечислены доступные формы кнопок и их описания.

Фигура
rectangular
pill
circle
square

logo_alignment

Выравнивание логотипа Google. Значение по умолчанию: left. Этот атрибут применяется только к типу кнопки standard. Дополнительную информацию можно найти в таблице ниже.

В таблице ниже перечислены доступные варианты выравнивания и их описания.

logo_alignment
left
center

ширина

Минимальная ширина кнопки в пикселях. Максимальная ширина – 400 пикселей.

Подробная информация приведена в таблице ниже.

locale

Необязательное поле. Текст кнопки будет показываться на указанном языке. Если язык не задан, то будет использоваться язык, выбранный в аккаунте Google или настройках браузера пользователя. Добавьте параметр hl и код языка в директиву src при загрузке библиотеки, например gsi/client?hl=<iso-639-code>.

Если правило не настроено, используется язык браузера по умолчанию или язык, выбранный пользователем в сеансе Google. Поэтому разные пользователи могут видеть разные версии локализованных кнопок, возможно, разных размеров.

Подробная информация приведена в таблице ниже.

click_listener

Вы можете определить функцию JavaScript, которая будет вызываться при нажатии кнопки "Войти с аккаунтом Google", используя атрибут click_listener.

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }
  

В этом примере при нажатии кнопки "Войти с аккаунтом Google" в консоль записывается сообщение Sign in with Google button clicked....

штат

Необязательный параметр. Поскольку на одной странице может быть несколько кнопок "Войти с аккаунтом Google", вы можете назначить каждой из них уникальную строку. Эта строка будет возвращена вместе с токеном идентификатора, чтобы вы могли определить, какую кнопку нажал пользователь для входа.

Подробная информация приведена в таблице ниже.

Тип данных: учетные данные.

При вызове функции native_callback в качестве параметра передается объект Credential. В таблице ниже перечислены поля, содержащиеся в объекте.

Метод: google.accounts.id.disableAutoSelect

Когда пользователь выходит из аккаунта на вашем сайте, вам нужно вызвать метод google.accounts.id.disableAutoSelect, чтобы записать статус в файлах cookie. Это предотвращает зацикливание UX. См. следующий фрагмент кода метода:

google.accounts.id.disableAutoSelect()

В примере кода ниже метод google.accounts.id.disableAutoSelect реализуется с помощью функции onSignout().

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

Метод: google.accounts.id.storeCredential

Этот метод является оболочкой для метода store() встроенного в браузер API Credential Manager. Поэтому его можно использовать только для хранения пароля. Пример кода:

google.accounts.id.storeCredential(Credential, callback)

В примере кода ниже метод google.accounts.id.storeCredential реализуется с помощью функции onSignIn().

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

Метод google.accounts.id.cancel

Вы можете отменить процесс One Tap, если удалите подсказку из DOM-модели доверяющей стороны. Если учетные данные уже выбраны, операция отмены игнорируется. Пример кода:

google.accounts.id.cancel()

В следующем примере кода метод google.accounts.id.cancel() реализуется с помощью функции onNextButtonClicked():

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

Обратный вызов загрузки библиотеки: onGoogleLibraryLoad

Вы можете зарегистрировать обратный вызов onGoogleLibraryLoad. Она получает уведомление после загрузки библиотеки JavaScript для функции "Войти с аккаунтом Google".

window.onGoogleLibraryLoad = () => {
    ...
};

Этот обратный вызов – просто сокращенный вариант обратного вызова window.onload. Различий в поведении нет.

В примере кода ниже показано, как реализовать обратный вызов onGoogleLibraryLoad.

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

Метод: google.accounts.id.revoke

Метод google.accounts.id.revoke отзывает разрешение на доступ по протоколу OAuth, которое используется для передачи токена идентификации указанного пользователя. См. следующий фрагмент кода метода: javascript google.accounts.id.revoke(login_hint, callback)

В примере кода ниже показано, как использовать метод revoke с идентификатором.

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

Тип данных: RevocationResponse.

При вызове функции callback в качестве параметра передается объект RevocationResponse. В таблице ниже перечислены поля, которые содержатся в объекте ответа на отзыв.

успешно

Это поле содержит логическое значение, которое равно true, если вызов метода revoke выполнен успешно, и false, если произошел сбой.

ошибка

Это поле содержит строковое значение и подробное сообщение об ошибке, если вызов метода revoke не удался. В случае успеха оно не определено.