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ę zarówno z przewodnikiem Łączenie tożsamości w UCP, w którym znajdziesz wymagania dotyczące poszczególnych usług, jak i z tą dokumentacją, w której znajdziesz szczegółowe informacje o podstawowym wdrożeniu 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 kont 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ępnianymi za zgodą użytkownika z profilu konta Google.

Możliwości i wymagania

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

Proces łączenia	Funkcje standardowe	Funkcje UCP
App Flip	Zalecane	Zalecane
Uproszczone łączenie	Zalecane	Zalecane
OAuth w internecie	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 tokena umożliwia synchronizację z wydarzeniami inicjowanymi przez Google, a funkcja ochrony międzykontowej (RISC) pozwala powiadamiać Google o wszelkich wydarzeniach odłączania, które mają miejsce na Twojej platformie.

Uwaga: większość dokumentacji 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 konta Google obejmuje odwrotny przypadek, w którym użytkownik usługi Google może uwierzytelniać się na Twojej platformie i wywoływać interfejsy API Twojej usługi. Jeśli chcesz używać OAuth 2.0 do uzyskiwania 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 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 za pomocą OAuth („OAuth w internecie”)

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

Łączenie OAuth obsługuje przepływy kodu autoryzacji i niejawne przepływy OAuth. 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 nie jest obsługiwany. Zamiast tego użyj przepływu kodu autoryzacji.

Uwaga: wdrożenie protokołu OAuth w internecie jest wymagane w przypadku wszystkich integracji łączenia kont, ponieważ jest to metoda rezerwowa w przypadku procesów przejścia do aplikacji i uproszczonych.

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

Łą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 oni 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 z użyciem przepływu kodu autoryzacji.

Funkcja App Flip jest obsługiwana zarówno na Android, jak i na 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 od użytkownika zgodę 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 uwierzytelniania OAuth lub procesu uwierzytelniania OAuth w internecie.

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 OAuth, dzięki czemu użytkownicy mogą dokończyć proces łączenia bez opuszczania platformy Google, co zmniejsza trudności i liczbę rezygnacji. Uproszczone łączenie oparte na OAuth zapewnia najlepsze wrażenia użytkownika dzięki płynnemu 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 podmiotu zewnętrznego.

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 zewnętrznej, korzystając z informacji przekazanych przez Google : adresu e-mail, imienia i nazwiska oraz zdjęcia profilowego, lub zalogować się i połączyć z innym adresem e-mail (w tym celu musi zalogować się w Twojej usłudze za pomocą protokołu Web 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 łączenia i przejścia do aplikacji zmniejszają trudności związane z łączeniem, ponieważ użytkownicy mogą ukończyć ten proces w kilku krokach. Połączenie OAuth w internecie wymaga najmniej wysiłku i jest dobrym punktem wyjścia. Następnie możesz dodać inne przepływy łączenia.

Uwaga: przepływ OAuth w internecie jest wymagany w przypadku wszystkich integracji, ponieważ jest to opcja rezerwowa dla innych przepływów.

Praca z tokenami

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

Praca z tokenami

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.

Token types

OAuth 2.0 uses strings called tokens to communicate between the user agent, the client application, and the OAuth 2.0 server.

Three types of OAuth 2.0 tokens can be used during account linking:

• Authorization code. A short-lived token that can be exchanged for an access and a refresh token. For security purposes, Google calls your authorization endpoint to obtain a single use or very short-lived code.

• Access token. A token that grants the bearer access to a resource. To limit exposure that could result from the loss of this token, it has a limited lifetime, usually expiring after an hour or so.

• Refresh token. A long-lived token that can be exchanged for a new access token when an access token expires. When your service integrates with Google, this token is exclusively stored and used by Google. Google calls your token exchange endpoint to exchange refresh tokens for access tokens, which are in turn used to access user data.

Token handling

Race conditions in clustered environments and client-server exchanges can result in complex timing and error handling scenarios when working with tokens. For example:

• You receive a request for a new access token, and you issue a new access token. Concurrently, you receive a request for access to your service's resource using the previous, unexpired access token.
• Your refresh token reply is yet to be received (or is never received) by Google. Meanwhile, the previously valid refresh token is used in a request from Google.

Requests and replies can arrive in any order, or not at all due to asynchronous services running in a cluster, network behavior, or other means.

Immediate and fully consistent shared state both within, and between, your and Google's token handling systems cannot be guaranteed. Multiple valid, unexpired tokens can coexist within or across systems short period of time. To minimize negative user impact we recommend you do the following:

• Accept unexpired access tokens, even after a newer token is issued.
• Use alternatives to Refresh Token Rotation.
• Support multiple, concurrently valid access and refresh tokens. For security, you should limit the number of tokens and token lifetime.

Maintenance and outage handling

During maintenance or unplanned outages Google might be unable to call your authorization or token exchange endpoints to obtain access and refresh tokens.

Your endpoints should respond with a 503 error code and empty body. In this case, Google retries failed token exchange requests for a limited time. Provided that Google is later able to obtain refresh and access tokens, failed requests are not visible to users.

Warning: Do not return a 400 error code and {"error": "invalid_grant"} body during maintenance or outages. Doing so deletes previously issued tokens and requires users to relink their accounts.

Failing requests for an access token result in a visible error, if initiated by a user. Users will be required to retry linking failures if the implicit OAuth 2.0 flow is used.

Recommendations

There are many solutions to minimize maintenance impact. Some options to consider:

• Maintain your existing service and route a limited number of requests to your newly updated service. Migrate all requests only after confirming expected functionality.

• Reduce the number of token requests during the maintenance period:

  • Limit maintenance periods to less than the access token lifetime.

  • Temporarily increase the access token lifetime:

    1. Increase token lifetime to greater than maintenance period.
    2. Wait twice the duration of your access token lifetime, enabling users to exchange short lived tokens for longer duration tokens.
    3. Enter maintenance.
    4. Respond to token requests with a 503 error code and empty body.
    5. Exit maintenance.
    6. Decrease token lifetime back to normal.

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 warunkom wyścigu i niezamierzonemu odłączeniu, które mogą wystąpić, jeśli zostanie wydany nowy token odświeżania, ale nie zostanie on pomyślnie odebrany lub zapisany przez Google.

Zarejestruj się przez Google

Aby włączyć łączenie kont, musimy poznać szczegóły konfiguracji OAuth 2.0 i udostępnić dane logowania. Szczegółowe informacje znajdziesz w sekcji rejestracja.