В этом руководстве рассказывается о внедрении 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.
Дальнейшие действия
Есть три варианта:
- Проведите оценку воздействия и при необходимости обновите веб-приложение. Этот подход позволяет определить, используются ли функции, требующие изменений в веб-приложении. Инструкции приведены в следующем разделе этого руководства.
- Перейдите на библиотеку Сервисов идентификации Google (GIS). Настоятельно рекомендуем перейти на последнюю поддерживаемую версию библиотеки входа. Для этого следуйте инструкциям.
- Ничего не предпринимать. Когда библиотека 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:
- Откройте страницу Credentials (Учетные данные) в Google API Console.
Убедитесь, что URI вашего сайта указан в разделе Разрешенные источники JavaScript. URI включает только схему и полное имя хоста. Пример:
https://www.example.com.При необходимости учетные данные можно возвращать с помощью перенаправления на конечную точку, размещенную вами, а не через обратный вызов JavaScript. В этом случае убедитесь, что ваши URI перенаправления указаны в разделе Authorized redirect URIs (Авторизованные URI перенаправления). URI перенаправления включают схему, полное имя хоста и путь и должны соответствовать правилам проверки URI перенаправления. Пример:
https://www.example.com/auth-receiver.
Тестирование
После выполнения инструкций в разделе "Настройка":
- Закройте все окна Chrome в режиме инкогнито и откройте новое окно в этом режиме. Это позволит очистить кеш и удалить файлы cookie.
- Загрузите страницу входа пользователя и попробуйте войти.
Чтобы выявить и устранить известные проблемы, следуйте инструкциям в следующих разделах этого руководства:
Проверьте, нет ли в консоли ошибок или предупреждений, связанных с библиотекой входа через Google.
Повторяйте эти действия, пока не сможете войти в аккаунт без ошибок. Чтобы убедиться, что вход выполнен успешно, проверьте, возвращает ли
BasicProfile.getEmail()ваш адрес электронной почты и равно лиGoogleUser.isSignedIn()значениюTrue.
Найдите запрос библиотеки входа через 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 Permissions Policy
allow="identity-credentials-get".
Повторите эти действия для каждого элемента 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 браузер запрашивает согласие пользователя в следующих случаях:
- пользователь впервые входит в веб-приложение, используя новый экземпляр браузера;
- Вызывается
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.