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

На этой справочной странице описывается API JavaScript для входа. Вы можете использовать этот API для отображения подсказки One Tap или кнопки «Войти через Google» на своих веб-страницах.

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

Метод google.accounts.id.initialize инициализирует клиент Sign In With 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 создает экземпляр клиента Sign In With Google, который может неявно использоваться всеми модулями на одной и той же веб-странице.

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

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

Тип данных: Идконфигуратион

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

ID клиента

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

авто Выбор

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

перезвонить

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

логин_ури

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

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

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

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

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

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

credential=ID_TOKEN

native_callback

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

cancel_on_tap_outside

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

prompt_parent_id

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

одноразовый номер

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

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

контекст

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

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

state_cookie_domain

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

ux_mode

Используйте это поле, чтобы настроить поток UX, используемый кнопкой «Войти через Google». Значение по умолчанию — popup . Этот атрибут не влияет на UX OneTap. Дополнительную информацию см. в следующей таблице:

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

allow_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 недопустимо, инициализация одним нажатием промежуточного режима iframe завершится ошибкой и остановится.

промежуточный_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 UX в браузерах, поддерживающих Intelligent Tracking Prevention (ITP). Значение по умолчанию — false . Дополнительную информацию см. в следующей таблице:

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

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

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

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

Уведомления срабатывают в следующие моменты:

• Момент отображения: это происходит после вызова метода 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 Web Token (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 GSuite email address
  "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's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

sub содержит глобальный уникальный идентификатор учетной записи Google.

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

Случаи, когда Google авторитетен:

• email имеет суффикс @gmail.com , это учетная запись Gmail.
• email_verified имеет значение true и установлен hd , это учетная запись G Suite.

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

select_by

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

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

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

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

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

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

Метод: 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	Стандартная тема кнопки:
filled_blue	Тема кнопки с синей заливкой:
filled_black	Тема кнопки с черной заливкой:

размер

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

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

Размер
large	Большая кнопка:
medium	Кнопка среднего размера:
small	Маленькая кнопка:

текст

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

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

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

Текст
signin_with	Текст кнопки «Войти через Google»:
signup_with	Текст кнопки «Зарегистрироваться в Google»:
continue_with	Текст кнопки «Продолжить с Google»:
signin	Текст кнопки «Войти»:

форма

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

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

Форма
rectangular	Кнопка прямоугольной формы. Если используется для типа кнопки icon , то это то же самое, что и square .
pill	Кнопка в виде таблетки. Если используется для типа кнопки icon , то это то же самое, что и circle .
circle	Кнопка в виде круга. Если используется для standard типа кнопки, то это то же самое, что и pill .
square	Кнопка квадратной формы. Если используется для standard типа кнопки, то это то же самое, что и rectangular .

logo_alignment

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

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

logo_alignment
left	Выравнивает логотип Google по левому краю.
center	Выравнивает логотип Google по центру.

ширина

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

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

место действия

Предустановленная локаль текста кнопки. Если он не установлен, используется локаль браузера по умолчанию или настройка пользователя сеанса 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 нажато... будет выведено на консоль при нажатии кнопки Войти с помощью 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 диспетчера учетных данных браузера. Поэтому его можно использовать только для хранения учетных данных пароля. См. следующий пример кода метода:

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, используемое для совместного использования токена идентификатора для указанного пользователя. См. следующий фрагмент кода метода: google.accounts.id.revoke(hint, callback)

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

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

Тип данных: RevocationResponse

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

успешный

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

ошибка

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