Przegląd

Wybierz ścieżkę integracji

Wybierz ścieżkę, która najlepiej odpowiada Twoim potrzebom:

Ścieżka	Urządzenia	Więcej informacji
Protokół Universal Commerce Protocol (UCP)	Sprzedawcy i detaliści.	Dokumentacja UCP
Standardowe łączenie kont	Inteligentny dom, telewizor i YouTube.	Dokumenty

Uwaga: te ścieżki integracji się uzupełniają. Jeśli wdrażasz UCP, zalecamy zapoznanie się z przewodnikiem UCP Identity Linking, w którym znajdziesz wymagania dotyczące poszczególnych produktów, oraz z tą dokumentacją, w której znajdziesz szczegółowe informacje o podstawowej implementacji protokołu OAuth.

Łączenie kont umożliwia posiadaczom kont Google szybkie, bezproblemowe i bezpieczne łączenie się z Twoimi usługami. Możesz wdrożyć łączenie z kontem Google, aby udostępniać dane użytkownika z Twojej platformy aplikacjom i usługom Google.

Bezpieczny protokół OAuth 2.0 umożliwia bezpieczne połączenie konta Google użytkownika z jego kontem na Twojej platformie, dzięki czemu aplikacje i urządzenia Google uzyskują dostęp do Twoich usług.

Użytkownicy mogą połączyć lub rozłączyć swoje konta i opcjonalnie utworzyć nowe konto na Twojej platformie za pomocą łączenia z kontem Google.

Przypadki użycia

Oto niektóre z powodów, dla których warto wdrożyć łączenie z kontem Google:

• udostępniać dane użytkownika z Twojej platformy aplikacjom i usługom Google;

• Zintegruj się z Zakupami Google i platformami AI (wyszukiwarka, Gemini) za pomocą protokołu Universal Commerce Protocol (UCP).

• Odtwarzaj filmy i programy telewizyjne za pomocą Google TV.

• zarządzanie połączonymi urządzeniami Google Smart Home i sterowanie nimi za pomocą aplikacji Google Home i Asystenta Google, np. „OK Google, włącz światła”;

• Twórz dostosowane do użytkownika funkcje i sposoby działania Asystenta Google za pomocą akcji konwersacyjnych, np. „OK Google, zamów to, co zwykle, w Starbucks”.

• Umożliwiać użytkownikom zdobywanie nagród za oglądanie kwalifikujących się transmisji na żywo w YouTube po połączeniu konta Google z kontem partnera oferującego nagrody.

• wstępne wypełnianie nowych kont podczas rejestracji danymi udostępnionymi za zgodą użytkownika z profilu konta Google;

Możliwości i wymagania

Poniższa tabela zawiera informacje o obsłudze i rekomendacjach dotyczących każdego procesu łączenia.

Proces łączenia	Funkcje standardowe	Funkcje UCP
App Flip	Zalecane	Zalecane
Uproszczone łączenie	Zalecane	Zalecane
Łączenie OAuth	Wymagane (reklama zastępcza)	Wymagane (reklama zastępcza)
OAuth 2.1	Zalecane	Zalecane

• Zwiększanie prywatności użytkowników przez definiowanie zakresów niestandardowych, aby udostępniać tylko niezbędne dane, oraz zwiększanie zaufania użytkowników przez jasne określanie, w jaki sposób ich dane są wykorzystywane.

• Dostęp do danych i usług hostowanych na Twojej platformie można cofnąć, rozłączając konta. Wdrożenie opcjonalnego punktu końcowego unieważniania tokenów umożliwia synchronizację z wydarzeniami inicjowanymi przez Google, a ochrona międzykontowa (RISC) pozwala powiadamiać Google o wszelkich wydarzeniach odłączania, które mają miejsce na Twojej platformie.

Uwaga: większość dokumentacji protokołu OAuth 2.0 dotyczącej Platformy tożsamości Google opisuje, jak logować użytkowników za pomocą ich kont Google i uzyskiwać autoryzację do wywoływania interfejsów API Google w ich imieniu. Łączenie kont Google obejmuje odwrotny przypadek, w którym użytkownik usługi Google może uwierzytelnić się na Twojej platformie i wywoływać interfejsy API Twojej usługi. Jeśli chcesz używać OAuth 2.0 na potrzeby dostępu do interfejsów API Google, zapoznaj się z dokumentacją klienta OAuth 2.0.

Procesy łączenia kont

Istnieją 3 procesy łączenia z kontem Google, które są oparte na protokole OAuth i wymagają zarządzania punktami końcowymi autoryzacji i wymiany tokenów zgodnymi z OAuth 2.0 lub kontrolowania ich.

Podczas procesu łączenia wydajesz Google tokeny dostępu do poszczególnych kont Google po uzyskaniu zgody właścicieli kont na połączenie kont i udostępnianie danych.

Łączenie OAuth

Jest to proces łączenia OAuth, który przekierowuje użytkowników do Twojej witryny w celu połączenia. Użytkownik zostanie przekierowany na Twoją stronę, aby zalogować się na swoje konto. Po zalogowaniu użytkownik wyraża zgodę na udostępnianie swoich danych w Twojej usłudze firmie Google. W tym momencie konto Google użytkownika i Twoja usługa zostaną połączone.

Łączenie OAuth obsługuje przepływy OAuth z kodem autoryzacji i niejawne. Usługa musi hostować punkt końcowy autoryzacji zgodny z protokołem OAuth 2.0 w przypadku przepływu niejawnego oraz udostępniać punkt końcowy autoryzacji i wymiany tokenów w przypadku przepływu kodu autoryzacji.

Ostrzeżenie: w przypadku przepływów MCP, UCP i przepływów opartych na działaniach agenta protokół OAuth 2.1 jest obowiązkowy, a przepływ niejawny jest nieobsługiwany. Zamiast tego użyj przepływu kodu autoryzacji.

Uwaga: w przypadku wszystkich integracji łączenia kont wymagane jest wdrożenie łączenia przez OAuth, ponieważ jest to metoda rezerwowa w przypadku przepływów App Flip i uproszczonych.

Rysunek 1. Łączenie kont na telefonie użytkownika za pomocą protokołu OAuth

Łączenie za pomocą przejścia do aplikacji opartego na OAuth („Przejście do aplikacji”)

Sposób obsługi protokołu OAuth, który kieruje użytkowników do aplikacji w celu połączenia kont.

Łączenie aplikacji oparte na OAuth prowadzi użytkowników podczas przechodzenia między zweryfikowanymi aplikacjami mobilnymi na Androida lub iOS a platformą Google, aby mogli przejrzeć proponowane zmiany w dostępie do danych i wyrazić zgodę na połączenie konta na Twojej platformie z kontem Google. Aby włączyć przejście do aplikacji, usługa musi obsługiwać łączenie za pomocą protokołu OAuth lub łączenie za pomocą Zaloguj się przez Google opartego na protokole OAuth przy użyciu przepływu kodu autoryzacji.

Funkcja App Flip jest obsługiwana na Android i iOS.

Jak to działa:

Aplikacja Google sprawdza, czy Twoja aplikacja jest zainstalowana na urządzeniu użytkownika:

• Jeśli aplikacja zostanie znaleziona, użytkownik zostanie „przekierowany” do Twojej aplikacji. Aplikacja uzyskuje zgodę użytkownika na połączenie konta z Google, a następnie „przekierowuje” go z powrotem do usługi Google.
• Jeśli aplikacja nie zostanie znaleziona lub podczas procesu przejścia do aplikacji wystąpi błąd, użytkownik zostanie przekierowany do uproszczonego procesu łączenia lub procesu łączenia OAuth.

Rysunek 2. Łączenie kont na telefonie użytkownika za pomocą przełączania aplikacji

Uproszczone połączenie oparte na OAuth („Uproszczone”)

Uproszczone łączenie za pomocą Logowania przez Google opartego na OAuth dodaje Logowanie przez Google do łączenia opartego na OAuth, dzięki czemu użytkownicy mogą ukończyć proces łączenia bez opuszczania platformy Google, co zmniejsza trudności i liczbę rezygnacji. Uproszczone łączenie oparte na OAuth zapewnia najlepszą wygodę użytkownika dzięki bezproblemowemu logowaniu, tworzeniu konta i łączeniu kont przez połączenie Zaloguj się przez Google z łączeniem OAuth. Usługa musi obsługiwać punkty końcowe autoryzacji i wymiany tokenów zgodne z protokołem OAuth 2.0. Dodatkowo punkt końcowy wymiany tokenów musi obsługiwać asercje tokena sieciowego JSON (JWT) i wdrażać intencje check, create i get.

Uwaga: w tym procesie użytkownik nigdy nie opuszcza usługi Google, więc aby proces działał prawidłowo, Google musi wyświetlać prośbę o zgodę w imieniu firmy zewnętrznej.

Jak to działa:

Google potwierdza konto użytkownika i przekazuje Ci te informacje:

• Jeśli w Twojej bazie danych istnieje konto użytkownika, użytkownik pomyślnie połączy swoje konto Google z kontem w Twojej usłudze.
• Jeśli w Twojej bazie danych nie ma konta użytkownika, może on utworzyć nowe konto usługi innej firmy, podając informacje przekazane przez Google: adres e-mail, imię i nazwisko oraz zdjęcie profilowe. Może też zalogować się i połączyć z innym adresem e-mail (w tym celu musi zalogować się w Twojej usłudze za pomocą połączenia OAuth).

Rysunek 3. Łączenie kont na telefonie użytkownika za pomocą uproszczonego łączenia

Którego procesu użyjesz?

Aby zapewnić użytkownikom jak najlepsze wrażenia z łączenia kont, zalecamy wdrożenie wszystkich ścieżek. Uproszczone procesy przechodzenia do aplikacji zmniejszają trudności związane z łączeniem, ponieważ użytkownicy mogą ukończyć ten proces w kilku krokach. Proces łączenia OAuth jest najmniej pracochłonny i warto od niego zacząć, a potem dodać inne procesy łączenia.

Uwaga: przepływ łączenia OAuth jest wymagany w przypadku wszystkich integracji, ponieważ jest to alternatywa dla innych przepływów.

Praca z tokenami

Łączenie z kontem Google jest oparte na standardzie branżowym OAuth 2.0.

Wydajesz Google tokeny dostępu do poszczególnych kont Google po uzyskaniu zgody właścicieli kont na połączenie kont i udostępnianie danych.

令牌类型

OAuth 2.0 使用称为令牌的字符串在用户代理、客户端应用和 OAuth 2.0 服务器之间进行通信。

在帐号关联期间，可以使用三种类型的 OAuth 2.0 令牌：

• 授权代码 。一种短期令牌，可以交换为访问令牌和刷新令牌。出于安全考虑，Google 会调用您的授权端点来获取一次性或短期代码。

• 访问令牌 。一种令牌，用于授予持有者对资源的访问权限。为了限制因丢失此令牌而可能造成的风险，此令牌的生命周期有限，通常会在大约一小时后过期。

• 刷新令牌 。一种长期令牌，当访问令牌过期时，可以交换为新的访问令牌。当您的服务与 Google 集成时，此令牌仅由 Google 存储和使用。Google 会调用您的令牌交换端点，以将刷新令牌交换为访问令牌，而访问令牌又用于访问用户数据。

令牌处理

在集群环境和客户端-服务器交换中，竞争条件可能会导致在使用令牌时出现复杂的时序和错误处理场景。 例如：

• 您收到有关新访问令牌的请求，并签发了新的访问令牌。同时，您收到有关使用之前未过期的访问令牌访问您服务资源的请求。
• Google 尚未收到（或永远不会收到）您的刷新令牌回复。与此同时，之前有效的刷新令牌在 Google 的请求中使用。

由于集群中运行的异步服务、网络行为或其他方式，请求和回复可能会以任何顺序到达，或者根本不会到达。

无法保证您的令牌处理系统和 Google 的令牌处理系统之间以及内部的即时且完全一致的共享状态。在短时间内，多个有效且未过期的令牌可能会在系统内或跨系统共存。为了最大限度地减少对用户的负面影响，我们建议您执行以下操作：

• 接受未过期的访问令牌，即使在签发新令牌后也是如此。
• 使用 刷新令牌轮替的替代方案。
• 支持多个同时有效的访问令牌和刷新令牌。出于安全考虑，您应限制令牌数量和令牌生命周期。

维护和服务中断处理

在维护期间或计划外中断期间，Google 可能无法调用您的授权端点或令牌交换端点来获取访问令牌和刷新令牌。

您的端点应返回 503 错误代码和空正文。在这种情况下，Google 会在有限的时间内重试失败的令牌交换请求。前提是 Google 稍后能够获取刷新令牌和访问令牌，否则用户将无法看到失败的请求。

**警告** ：请勿在维护或中断期间返回 400 错误代码和 {"error": "invalid_grant"} 正文 。这样做会删除之前签发的令牌，并要求用户重新关联其帐号。

如果用户发起的访问令牌请求失败，则会导致显示错误。如果使用隐式 OAuth 2.0 流程，则用户需要重试关联失败。

建议

有很多解决方案可以最大限度地减少维护影响。您可以考虑以下选项：

• 维护现有服务，并将有限数量的请求路由到新更新的服务。仅在确认预期功能后才迁移所有请求。

• 减少维护期间的令牌请求数量：

  • 将维护期限制为小于访问令牌生命周期。

  • 暂时延长访问令牌生命周期：

    1. 将令牌生命周期延长到大于维护期。
    2. 等待访问令牌生命周期的两倍时长，以便用户将短期令牌交换为长期令牌。
    3. 进入维护期。
    4. 使用 503 错误代码和空正文响应令牌请求。
    5. 退出维护期。
    6. 将令牌生命周期缩短回正常水平。

Trwałe linkowanie

Trwałe połączenie to podstawowe wymaganie w przypadku stabilnych integracji. Dzięki temu konta użytkowników pozostają połączone nawet w przypadku przejściowych awarii sieci lub okresowego odświeżania danych logowania.

Aby wdrożyć trwałe linkowanie, zastosuj metodę „okna przesuwnego”: zamiast obracać dotychczasowy token odświeżania, przedłuż jego ważność (zgodnie z sekcją 6 RFC 6749). Zapobiega to sytuacjom wyścigu i niezamierzonemu odłączaniu, które mogą wystąpić, jeśli zostanie wydany nowy token odświeżania, ale nie zostanie on pomyślnie odebrany ani zapisany przez Google.

Zarejestruj się przez Google

Aby umożliwić połączenie kont, potrzebujemy szczegółów konfiguracji OAuth 2.0 i danych logowania. Szczegółowe informacje znajdziesz w sekcji rejestracja.