Вход с аккаунтом Google и FedCM API

В этом руководстве рассказывается о внедрении FedCM API в библиотеку платформы Google Sign-In. В частности, вы узнаете о хронологии и дальнейших действиях по обратно совместимому обновлению библиотеки, о том, как оценить последствия и убедиться, что вход пользователей по-прежнему работает, а также, если необходимо, о том, как обновить веб-приложение. Кроме того, мы расскажем, как управлять переходным периодом и получить помощь.

Статус библиотеки

Новые веб-приложения не смогут использовать устаревшую библиотеку платформы Google Sign-In, а приложения, в которых она уже используется, смогут продолжать работу до дальнейшего уведомления. Окончательная дата прекращения поддержки библиотеки пока не установлена. Подробнее о прекращении поддержки и закрытии…

В библиотеку входа с аккаунтом Google добавлены FedCM API с обратной совместимостью. Хотя большинство изменений не требуют действий с вашей стороны, обновление вносит изменения в запросы пользователей, permissions-policy для iframe и Content Security Policy (CSP). Эти изменения могут повлиять на ваше веб-приложение и потребовать изменений в коде приложения и конфигурации сайта.

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

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

Хронология

Последнее обновление: апрель 2025 г.

Ниже приведены даты и изменения, которые влияют на процесс входа пользователей.

  • Март 2023 г. Прекращение поддержки библиотеки платформы Google Sign-In.
  • Июль 2024 г. Начинается переходный период. В библиотеку платформы входа с аккаунтом Google добавляется поддержка FedCM API. По умолчанию Google контролирует процент запросов на вход пользователей с помощью FedCM в течение этого времени, а веб-приложения могут явно переопределить это поведение с помощью параметра use_fedcm.
  • Август 2025 г. Обязательное внедрение FedCM API в библиотеку платформы Google Sign-In.

Дальнейшие действия

Есть три варианта:

  1. Проведите оценку воздействия и при необходимости обновите веб-приложение. Этот подход позволяет определить, используются ли функции, требующие изменений в веб-приложении. Инструкции приведены в следующем разделе этого руководства.
  2. Перейдите на библиотеку Сервисов идентификации Google (GIS). Настоятельно рекомендуем перейти на последнюю поддерживаемую версию библиотеки входа. Для этого следуйте инструкциям.
  3. Ничего не предпринимать. Когда библиотека Google Sign-In перейдет на FedCM API для входа пользователей, ваше веб-приложение будет обновлено автоматически. Это самый простой способ, но есть риск, что пользователи не смогут войти в ваше веб-приложение.

Проведение оценки воздействия

Следуйте этим инструкциям, чтобы определить, можно ли обновить ваше веб-приложение с помощью обратно совместимого обновления или же необходимы изменения, чтобы пользователи могли входить в систему, когда библиотека платформы Google Sign-In полностью перейдет на FedCM API.

Настройка

Чтобы использовать FedCM при входе пользователя, необходимы API браузера и последняя версия библиотеки платформы входа в Google.

Прежде чем продолжить:

  • Обновите Chrome для компьютеров до последней версии. Для Chrome на Android требуется версия M128 или более поздняя. Тестирование в более ранних версиях невозможно.
  • При инициализации библиотеки платформы входа через Google в веб-приложении задайте для use_fedcm значение true. Обычно инициализация JavaScript выглядит следующим образом:

    • gapi.client.init({use_fedcm: true}) или
    • gapi.auth2.init({use_fedcm: true}) или
    • gapi.auth2.authorize({use_fedcm: true}).

    Вы также можете использовать тег meta, чтобы включить FedCM в HTML:

    • <meta name="google-signin-use_fedcm" content="true">
  • Аннулируйте кешированные версии библиотеки платформы входа с аккаунтом Google. Обычно этот шаг не требуется, поскольку последняя версия библиотеки скачивается непосредственно в браузер, если в тег <script src> включить api.js, client.js или platform.js (в запросе можно использовать любое из этих названий пакетов для библиотеки).

  • Подтвердите настройки OAuth для идентификатора клиента OAuth:

    1. Откройте страницу Credentials (Учетные данные) в Google API Console.
    2. Убедитесь, что URI вашего сайта указан в разделе Разрешенные источники JavaScript. URI включает только схему и полное имя хоста. Пример: https://www.example.com.

    3. При необходимости учетные данные можно возвращать с помощью перенаправления на конечную точку, размещенную вами, а не через обратный вызов JavaScript. В этом случае убедитесь, что ваши URI перенаправления указаны в разделе Authorized redirect URIs (Авторизованные URI перенаправления). URI перенаправления включают схему, полное имя хоста и путь и должны соответствовать правилам проверки URI перенаправления. Пример: https://www.example.com/auth-receiver.

Тестирование

После выполнения инструкций в разделе "Настройка":

Найдите запрос библиотеки входа через Google.

Проверьте, нужно ли изменить permissions-policy и Content Security Policy, изучив запрос к библиотеке платформы входа с аккаунтом Google. Для этого найдите запрос по названию и источнику библиотеки:

  • В Chrome откройте панель Сеть в Инструментах разработчика и перезагрузите страницу.
  • Чтобы найти запрос библиотеки, используйте значения в столбцах Домен и Название.
    • Домен – apis.google.com, а
    • Название соответствует значению "api.js", "client.js" или "platform.js". Конкретное значение Name зависит от пакета библиотеки, запрошенного документом.

Например, отфильтруйте по значению apis.google.com в столбце Домен и по значению platform.js в столбце Название.

Проверьте заголовок Permissions-Policy для iframe

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

Выполните инструкции из раздела Как найти запрос библиотеки входа через Google, выберите запрос библиотеки входа через Google на панели Сеть в Инструментах разработчика и найдите заголовок Sec-Fetch-Site в разделе Заголовки запросов на вкладке Заголовки. Если значение заголовка:

  • same-site или same-origin, то правила в отношении междоменных запросов не применяются и никаких изменений не требуется.
  • Если используется iframe, может потребоваться изменить cross-site.

Чтобы проверить, есть ли на странице iframe, выполните следующие действия:

  • Выберите панель Элементы в инструментах разработчика Chrome.
  • Чтобы найти iframe в документе, нажмите Ctrl + F.

Если iframe найден, проверьте документ на наличие вызовов функций gapi.auth2 или директив script src, которые загружают библиотеку Google Sign-In в iframe. В этом случае сделайте следующее.

Повторите эти действия для каждого элемента iframe в документе. Элементы iframe могут быть вложенными, поэтому не забудьте добавить директиву allow во все родительские элементы iframe.

Проверьте Content Security Policy

Если на вашем сайте используется Content Security Policy, вам может потребоваться обновить CSP, чтобы разрешить использование библиотеки входа с аккаунтом Google.

Выполните инструкции из раздела Как найти запрос библиотеки входа с аккаунтом Google. Затем выберите запрос библиотеки входа с аккаунтом Google на панели Сеть в Инструментах разработчика и найдите заголовок Content-Security-Policy в разделе Заголовки ответа на вкладке Заголовки.

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

  • Добавление https://apis.google.com/js/, https://accounts.google.com/gsi/ и https://acounts.google.com/o/fedcm/ в любые директивы connect-src, default-src или frame-src.

  • Добавление https://apis.google.com/js/bundle-name.js в директиву script-src. Замените bundle-name.js на api.js, client.js или platform.js в зависимости от того, какой пакет библиотек запрашивает документ.

Проверьте, не изменился ли запрос пользователя

Есть некоторые различия в поведении подсказок для пользователей: FedCM добавляет модальное диалоговое окно, отображаемое браузером, и обновляет требования к действиям пользователя.

Изображение модального диалогового окна FedCM

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

Активация пользователя

В FedCM обновлены требования к активации пользователем. Нажатие кнопки или клик по ссылке – это примеры жестов пользователя, которые позволяют сторонним источникам выполнять сетевые запросы или сохранять данные. При использовании FedCM браузер запрашивает согласие пользователя в следующих случаях:

  • пользователь впервые входит в веб-приложение, используя новый экземпляр браузера;
  • Вызывается GoogleAuth.signIn.

Сегодня, если пользователь уже входил на ваш сайт, вы можете получить его учетные данные при инициализации библиотеки входа с аккаунтом Google с помощью gapi.auth2.init без дополнительных действий со стороны пользователя. Теперь это возможно, только если пользователь хотя бы раз выполнил вход через FedCM.

Если вы включите FedCM и вызовете GoogleAuth.signIn, то при следующем посещении вашего сайта gapi.auth2.init сможет получить информацию о входе пользователя во время инициализации без его участия.

Примеры использования

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

  • Интеграция входа с аккаунтом Google в веб-приложение

    В этой демонстрации кнопка отображается с помощью элемента <div> и класса, а для уже вошедших в систему пользователей событие onload страницы возвращает учетные данные пользователя. Для входа и создания нового сеанса требуется взаимодействие с пользователем.

    Инициализация библиотеки выполняется классом g-signin2, который вызывает gapi.load и gapi.auth2.init.

    Жест пользователя, событие элемента <div> onclick, вызывает auth2.signIn во время входа или auth2.signOut во время выхода.

  • Как создать собственную кнопку "Войти с аккаунтом Google"

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

    Инициализация библиотеки выполняется с помощью события onload для библиотеки platform.js, а кнопка отображается с помощью gapi.signin2.render.

    Жест пользователя, нажатие кнопки входа, вызывает auth2.signIn.

    Во втором примере для управления внешним видом кнопки входа используются элемент <div>, стили CSS и пользовательская графика. Для входа и начала нового сеанса требуется взаимодействие с пользователем.

    Инициализация библиотеки выполняется при загрузке документа с помощью функции start, которая вызывает gapi.load, gapi.auth2.init и gapi.auth2.attachClickHandler.

    Жест пользователя, событие onclick элемента <div>, вызывает auth2.signIn с помощью auth2.attachClickHandler при входе или auth2.signOut при выходе.

  • Отслеживание состояния сеанса пользователя

    В этой демонстрации для входа и выхода пользователя используется нажатие кнопки. Для входа и создания нового сеанса требуется взаимодействие с пользователем.

    Инициализация библиотеки выполняется путем прямого вызова gapi.load, gapi.auth2.init и gapi.auth2.attachClickHandler() после загрузки platform.js с помощью script src.

    Жест пользователя, событие onclick элемента <div>, вызывает auth2.signIn с помощью auth2.attachClickHandler при входе или auth2.signOut при выходе.

  • Запрос дополнительных разрешений

    В этой демоверсии нажатие кнопки используется для запроса дополнительных областей действия OAuth 2.0 и получения нового токена доступа, а для уже вошедших в систему пользователей событие onload страницы возвращает учетные данные пользователя. Для входа и начала нового сеанса требуется взаимодействие с пользователем.

    Инициализация библиотеки выполняется событием onload для библиотеки platform.js через вызов gapi.signin2.render.

    Жест пользователя, нажатие на элемент <button>, запускает запрос дополнительных областей действия OAuth 2.0 с помощью googleUser.grant или auth2.signOut при выходе.

  • Интеграция входа с аккаунтом Google с помощью прослушивателей

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

    Инициализация библиотеки выполняется при загрузке документа с помощью функции start, которая вызывает gapi.load, gapi.auth2.init и gapi.auth2.attachClickHandler. Затем auth2.isSignedIn.listen и auth2.currentUser.listen используются для настройки уведомлений об изменениях состояния сеанса. Наконец, вызывается метод auth2.SignIn, который возвращает учетные данные пользователей, выполнивших вход.

    Жест пользователя, событие onclick элемента <div>, вызывает auth2.signIn с помощью auth2.attachClickHandler при входе или auth2.signOut при выходе.

  • Вход с аккаунтом Google для серверных приложений

    В этой демонстрации жест пользователя используется для запроса кода авторизации OAuth 2.0, а обратный вызов JS выполняет вызов AJAX, чтобы отправить ответ на бэкенд-сервер для проверки.

    Инициализация библиотеки выполняется с помощью события onload для библиотеки platform.js, которая использует функцию start для вызова gapi.load и gapi.auth2.init.

    Жест пользователя, нажатие на элемент <button>, запускает запрос кода авторизации путем вызова auth2.grantOfflineAccess.

  • Межплатформенная система единого входа

    FedCM требует согласия для каждого экземпляра браузера, даже если пользователи Android уже вошли в систему, необходимо однократное согласие.

Управление переходным периодом

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

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

Включить

Вы можете управлять тем, какие попытки входа на ваш сайт будут использовать FedCM API. Для этого при инициализации библиотеки платформы задайте для use_fedcm значение true. В этом случае запрос на вход пользователя использует FedCM API.

Отключить

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

После обязательного перехода библиотека платформы Google Sign-In будет игнорировать любые настройки use_fedcm.

Справка

Выполните поиск или задайте вопрос на сайте Stack Overflow, используя тег google-signin.