Справочник по входу с помощью Google HTML API

Эта справочная страница описывает API атрибутов HTML-данных Sign In With Google. Вы можете использовать API для отображения подсказки One Tap или кнопки Sign In With Google на своих веб-страницах.

Элемент с идентификатором "g_id_onload"

Вы можете поместить атрибуты данных Sign In With Google в любые видимые или невидимые элементы, такие как <div> и <span> . Единственное требование — чтобы идентификатор элемента был установлен на g_id_onload . Не помещайте этот идентификатор в несколько элементов.

Атрибуты данных

В следующей таблице перечислены атрибуты данных с их описаниями:

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

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

данные-client_id

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

данные-авто_промпт

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

данные-авто_выбор

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

данные-login_uri

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

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

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

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

Дополнительную информацию смотрите в следующей таблице:

Ваша конечная точка входа должна обрабатывать запросы POST, содержащие ключ credential со значением токена идентификатора в теле.

Ниже приведен пример запроса к вашей конечной точке входа:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

данные-обратный вызов

Этот атрибут — имя функции JavaScript, которая обрабатывает возвращаемый токен ID. Дополнительную информацию см. в следующей таблице:

Может использоваться один из атрибутов data-login_uri и data-callback . Это зависит от следующих компонентов и конфигураций режима UX:

• Атрибут data-login_uri необходим для режима redirect кнопки «Войти через Google», который игнорирует атрибут data-callback .

• Один из этих двух атрибутов должен быть установлен для Google One Tap и popup UX-режима кнопки входа в Google. Если установлены оба, атрибут data-callback имеет более высокий приоритет.

Функции JavaScript в пространстве имен не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

данные-native_login_uri

Этот атрибут — URL конечной точки обработчика учетных данных вашего пароля. Если вы установите атрибут data-native_login_uri или атрибут data-native_callback , библиотека JavaScript вернется к встроенному менеджеру учетных данных, когда нет сеанса Google. Вам не разрешено устанавливать оба атрибута data-native_callback и data-native_login_uri . Дополнительную информацию см. в следующей таблице:

данные-native_callback

Этот атрибут — имя функции JavaScript, которая обрабатывает учетные данные пароля, возвращаемые встроенным менеджером учетных данных браузера. Если вы устанавливаете атрибут data-native_login_uri или атрибут data-native_callback , библиотека JavaScript возвращается к встроенному менеджеру учетных данных, когда нет сеанса Google. Вам не разрешено устанавливать и data-native_callback , и data-native_login_uri . Дополнительную информацию см. в следующей таблице:

Функции JavaScript в пространстве имен не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

data-native_id_param

При отправке учетных данных пароля в конечную точку обработчика учетных данных пароля можно указать имя параметра для поля credential.id . Имя по умолчанию — email . Дополнительную информацию см. в следующей таблице:

data-native_password_param

При отправке учетных данных пароля в конечную точку обработчика учетных данных пароля можно указать имя параметра для значения credential.password . Имя по умолчанию — password . Дополнительную информацию см. в следующей таблице:

данные-отмена_при_отводе_снаружи

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

data-prompt_parent_id

Этот атрибут задает DOM ID элемента-контейнера. Если он не задан, в правом верхнем углу окна отображается подсказка One Tap. Дополнительную информацию см. в следующей таблице:

данные-skip_prompt_cookie

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

данные-nonce

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

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

данные-контекст

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

Дополнительную информацию смотрите в следующей таблице:

В следующей таблице перечислены все доступные контексты и их описания:

data-moment_callback

Этот атрибут является именем функции прослушивателя уведомлений о статусе подсказки UI. Для получения дополнительной информации обратитесь к типу данных PromptMomentNotification .

Дополнительную информацию смотрите в следующей таблице:

Функции JavaScript в пространстве имен не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

data-state_cookie_domain

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

данные-ux_mode

Этот атрибут задает поток UX, используемый кнопкой Sign In With Google. Значение по умолчанию — popup . Этот атрибут не влияет на One Tap UX. Дополнительную информацию см. в следующей таблице:

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

данные-разрешенные_родительские_источники

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

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

Если значение атрибута data-allowed_parent_origin недействительно, инициализация одним нажатием промежуточного режима 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" считается недействительным.

data-intermediate_iframe_close_callback

Переопределяет поведение промежуточного iframe по умолчанию, когда пользователи вручную закрывают One Tap, нажимая кнопку «X» в One Tap UI. Поведение по умолчанию — немедленное удаление промежуточного iframe из DOM.

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

Функции JavaScript в пространстве имен не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

данные-itp_support

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

data-login_hint

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

Более подробную информацию см. в документации OpenID Connect для login_hint .

данные-hd

Если у пользователя несколько учетных записей, и он должен входить только с помощью своей учетной записи Workspace, используйте это, чтобы предоставить Google подсказку доменного имени. В случае успеха учетные записи пользователей, отображаемые во время выбора учетной записи, ограничиваются предоставленным доменом. Подстановочное значение: * предлагает пользователю только учетные записи Workspace и исключает учетные записи потребителей ([email protected]) во время выбора учетной записи.

Более подробную информацию см. в документации OpenID Connect для hd .

данные-use_fedcm_for_prompt

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

данные-использование_fedcm_для_кнопки

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

data-button_auto_select

Это поле определяет, следует ли включить опцию автоматического выбора для потока кнопок FedCM. Если эта опция включена, возвращающиеся пользователи с активным сеансом Google будут автоматически входить в систему, минуя запрос Account Chooser. Значение по умолчанию — false . Вам необходимо явно включить функцию автоматического входа с помощью кнопки во время запуска подписки. Дополнительную информацию см. в следующей таблице:

Элемент с классом "g_id_signin"

Если добавить g_id_signin к атрибуту class элемента, элемент отобразится как кнопка «Войти через Google».

Вы можете отобразить несколько кнопок Sign In With Google на одной странице. Каждая кнопка может иметь собственные визуальные настройки. Настройки определяются следующими атрибутами данных.

Атрибуты визуальных данных

В следующей таблице перечислены атрибуты визуальных данных и их описания:

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

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

тип данных

Тип кнопки. Значение по умолчанию — standard . Дополнительную информацию см. в следующей таблице:

В следующей таблице перечислены все доступные типы кнопок и их описания:

Тип
standard
icon

дата-тема

Тема кнопки. Значение по умолчанию — outline . Дополнительную информацию см. в следующей таблице:

В следующей таблице перечислены доступные темы и их описания:

Тема
outline
filled_blue
filled_black

размер данных

Размер кнопки. Значение по умолчанию — large . Дополнительную информацию см. в следующей таблице:

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

Размер
large
medium
small

данные-текст

Текст кнопки. Значение по умолчанию — signin_with . Для текста кнопок-значков, имеющих разные атрибуты data-text визуальных различий нет. Единственное исключение — когда текст читается для обеспечения доступности экрана.

Дополнительную информацию смотрите в следующей таблице:

В следующей таблице перечислены доступные тексты кнопок и их описания:

Текст
signin_with
signup_with
continue_with
signin

форма данных

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

В следующей таблице перечислены доступные формы кнопок и их описания:

Форма
rectangular
pill
circle
square

data-logo_alignment

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

В следующей таблице перечислены доступные выравнивания и их описания:

logo_alignment
left
center

ширина данных

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

Дополнительную информацию смотрите в следующей таблице:

данные-локаль

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

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

Дополнительную информацию смотрите в следующей таблице:

данные-щелчок_слушатель

С помощью атрибута data-click_listener можно определить функцию JavaScript, которая будет вызываться при нажатии кнопки «Войти через Google».

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

В этом примере сообщение Нажата кнопка «Войти через Google»... регистрируется в консоли при нажатии кнопки «Войти через Google».

данные-состояние

Необязательно, поскольку на одной странице может отображаться несколько кнопок Sign in with Google, вы можете назначить каждой кнопке уникальную строку. Та же строка будет возвращена вместе с токеном ID, так что вы сможете определить, какую кнопку нажал пользователь для входа.

Дополнительную информацию смотрите в следующей таблице:

Интеграция на стороне сервера

Ваши конечные точки на стороне сервера должны обрабатывать следующие HTTP-запросы POST .

Конечная точка обработчика токена ID

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

HTTP-запрос POST содержит следующую информацию:

удостоверение

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

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 GSuite email address
  "email": "[email protected]", // 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": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's 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_verified также может быть истинным, поскольку Google изначально проверил пользователя при создании учетной записи Google, однако с тех пор владелец учетной записи электронной почты третьей стороны мог измениться.

Поле exp показывает время истечения срока действия токена на стороне вашего сервера . Для токена ID, полученного с помощью Sign In With Google, это один час. Вам необходимо проверить токен до истечения срока действия. Не используйте exp для управления сеансом. Истекший срок действия токена ID не означает, что пользователь вышел из системы. Ваше приложение отвечает за управление сеансом ваших пользователей.

select_by

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

• Пользователь нажал кнопку «Одно касание» или «Войти через Google» или использовал бесконтактный автоматический процесс входа.

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

• Перед тем как предоставить вашему приложению учетные данные токена ID, пользователь должен либо

  • нажали кнопку «Подтвердить», чтобы дать свое согласие на передачу учетных данных, или
  • ранее предоставили согласие и использовали функцию «Выбрать учетную запись», чтобы выбрать учетную запись Google.

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

состояние

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

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

Конечная точка обработчика учетных данных пароля

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

HTTP-запрос POST содержит следующую информацию: