Dokumentacja interfejsu HTML API Logowanie przez Google

Ta strona referencyjna opisuje interfejs API atrybutów danych HTML funkcji Zaloguj się przez Google, który służy do wyświetlania przycisku Zaloguj się przez Google lub promptu One Tap na stronach internetowych.

Element o identyfikatorze „g_id_onload”

Atrybuty danych funkcji Zaloguj się przez Google możesz umieścić w dowolnych widocznych lub niewidocznych elementach, takich jak <div> i <span>. Jedynym wymaganiem jest ustawienie identyfikatora elementu na g_id_onload. Nie umieszczaj tego identyfikatora w wielu elementach.

Atrybuty danych

W tabeli poniżej znajdziesz listę atrybutów danych wraz z ich opisami:

Typy atrybutów

W poniższych sekcjach znajdziesz szczegółowe informacje o poszczególnych typach atrybutów oraz przykłady.

data-client_id

Ten atrybut to identyfikator klienta aplikacji, który można znaleźć i utworzyć w konsoli Google Cloud. Więcej informacji znajdziesz w tej tabeli:

data-color_scheme

To pole zawiera schemat kolorów zastosowany do promptu One Tap. Więcej informacji znajdziesz w tabeli poniżej:

W tabeli poniżej znajdziesz dostępne schematy kolorów i ich opisy.

data-auto_prompt

Ten atrybut określa, czy wyświetlać funkcję One Tap. Wartością domyślną jest true. Gdy ta wartość to false, funkcja Google One Tap nie jest wyświetlana. Więcej informacji znajdziesz w tabeli poniżej:

data-auto_select

Ten atrybut określa, czy token identyfikacji ma być zwracany automatycznie, bez interakcji użytkownika, jeśli tylko jedna sesja Google zatwierdziła Twoją aplikację. Wartość domyślna to false. Więcej informacji znajdziesz w tej tabeli:

data-login_uri

Ten atrybut to identyfikator URI punktu końcowego logowania.

Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0, które zostały skonfigurowane na platformie Google Auth, i musi być zgodna z naszymi regułami sprawdzania poprawności identyfikatorów URI przekierowania.

Ten atrybut można pominąć, jeśli bieżąca strona jest stroną logowania. W takim przypadku dane logowania są domyślnie publikowane na tej stronie.

Odpowiedź z danymi logowania z tokenem identyfikacji jest wysyłana do punktu końcowego logowania, gdy nie jest zdefiniowana funkcja wywołania zwrotnego, a użytkownik kliknie przycisk Zaloguj się przez Google lub One Tap albo nastąpi automatyczne logowanie.

Twój punkt końcowy logowania musi obsługiwać żądania POST zawierające w treści parametr credential z wartością tokena identyfikacji.

Więcej informacji znajdziesz w tej tabeli:

data-callback

Ten atrybut to nazwa funkcji JavaScriptu, która obsługuje zwrócony token identyfikacji. Więcej informacji znajdziesz w tej tabeli:

Można użyć jednego z atrybutów data-login_uri i data-callback. Zależy to od tych konfiguracji komponentów i trybów UX:

• Atrybut data-login_uri jest wymagany w przypadku trybu UX redirect przycisku Zaloguj się przez Google, który ignoruje atrybut data-callback.

• Jeden z tych 2 atrybutów musi być ustawiony dla funkcji Google One Tap i przycisku Logowanie przez Google w trybie UX popup. Jeśli skonfigurowane są obie zasady, pierwszeństwo ma atrybut data-callback.

Funkcje JavaScriptu w przestrzeni nazw nie są obsługiwane przez interfejs HTML API. Zamiast tego użyj globalnej funkcji JavaScriptu bez przestrzeni nazw. Na przykład użyj mylibCallback zamiast mylib.callback.

Funkcja wywołania zwrotnego otrzymuje obiekt CredentialResponse jako parametr. Szczegółowe informacje o możliwych wartościach odpowiedzi znajdziesz w CredentialResponse.

data-native_login_uri

Ten atrybut to adres URL punktu końcowego modułu obsługi danych logowania za pomocą hasła. Jeśli ustawisz atrybut data-native_login_uri lub data-native_callback, biblioteka JavaScriptu będzie używać wbudowanego menedżera danych logowania, gdy nie będzie sesji Google. Nie możesz ustawić jednocześnie atrybutów data-native_callback i data-native_login_uri. Więcej informacji znajdziesz w tej tabeli:

data-native_callback

Ten atrybut to nazwa funkcji JavaScript, która obsługuje dane logowania (hasło) zwrócone przez wbudowany Credential Manager przeglądarki. Jeśli ustawisz atrybut data-native_login_uri lub data-native_callback, biblioteka JavaScriptu będzie korzystać z wbudowanego menedżera danych logowania, gdy nie będzie sesji Google. Nie możesz ustawić jednocześnie data-native_callback i data-native_login_uri. Więcej informacji znajdziesz w tej tabeli:

Funkcje JavaScriptu w przestrzeni nazw nie są obsługiwane przez interfejs HTML API. Zamiast tego użyj globalnej funkcji JavaScriptu bez przestrzeni nazw. Na przykład użyj mylibCallback zamiast mylib.callback.

data-native_id_param

Gdy przesyłasz dane logowania do punktu końcowego modułu obsługi danych logowania, możesz określić nazwę parametru dla pola credential.id. Domyślna nazwa to email. Więcej informacji znajdziesz w tej tabeli:

data-native_password_param

Gdy przesyłasz dane logowania do punktu końcowego modułu obsługi danych logowania, możesz określić nazwę parametru dla wartości credential.password. Domyślna nazwa to password. Więcej informacji znajdziesz w tej tabeli:

data-cancel_on_tap_outside

Ten atrybut określa, czy anulować żądanie logowania jednym dotknięciem, jeśli użytkownik kliknie poza promptem. Wartością domyślną jest true. Aby wyłączyć tę funkcję, ustaw wartość na false. Więcej informacji znajdziesz w tej tabeli:

data-prompt_parent_id

Ten atrybut ustawia identyfikator DOM elementu kontenera. Jeśli nie jest ustawiony, okno logowania jednym dotknięciem wyświetla się w prawym górnym rogu okna. Więcej informacji znajdziesz w tabeli poniżej:

data-skip_prompt_cookie

Używa pliku cookie do kontrolowania wyświetlania promptu One Tap. Jeśli plik cookie określony przez ten atrybut ma niepustą wartość, komunikat nie jest wyświetlany. Więcej informacji znajdziesz w tej tabeli:

data-nonce

Ten atrybut to losowy ciąg znaków używany przez token identyfikacji do zapobiegania atakom metodą powtórzenia. Więcej informacji znajdziesz w tej tabeli:

Długość liczby jednorazowej jest ograniczona do maksymalnego rozmiaru JWT obsługiwanego przez Twoje środowisko oraz do indywidualnych ograniczeń rozmiaru HTTP przeglądarki i serwera.

data-essential_claims

Ten atrybut to ciąg znaków używany do żądania dodatkowych deklaracji, które mają zostać uwzględnione w tokenie identyfikacji zwracanym przez Google. Pełną listę deklaracji akceptowanych przez Google znajdziesz w artykule Obsługiwane deklaracje.

Więcej informacji znajdziesz w tej tabeli:

data-context

To pole zmienia tekst tytułu i wiadomości wyświetlanych w oknie logowania jednym dotknięciem. Nie ma wpływu na przeglądarki z funkcją ITP. Domyślna wartość to signin.

Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz wszystkie dostępne konteksty i ich opisy:

data-moment_callback

Ten atrybut to nazwa funkcji detektora powiadomień o stanie interfejsu promptu. Więcej informacji znajdziesz w opisie typu danych PromptMomentNotification.

Więcej informacji znajdziesz w tej tabeli:

Funkcje JavaScriptu w przestrzeni nazw nie są obsługiwane przez interfejs HTML API. Zamiast tego użyj globalnej funkcji JavaScriptu bez przestrzeni nazw. Na przykład użyj mylibCallback zamiast mylib.callback.

data-state_cookie_domain

Jeśli chcesz wyświetlać funkcję One Tap w domenie nadrzędnej i jej subdomenach, przekaż domenę nadrzędną do tego atrybutu, aby używany był pojedynczy plik cookie stanu udostępniania. Więcej informacji znajdziesz w tej tabeli:

data-ux_mode

Ten atrybut określa proces UX używany przez przycisk Zaloguj się przez Google. Wartością domyślną jest popup. Ten atrybut nie ma wpływu na UX funkcji One Tap. Więcej informacji znajdziesz w tabeli poniżej:

W tabeli poniżej znajdziesz dostępne tryby UX i ich opisy.

data-allowed_parent_origin

Źródła, które mogą umieszczać pośredni element iframe. Jeśli ten atrybut jest obecny, funkcja One Tap działa w trybie pośredniego elementu iframe. Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz obsługiwane typy wartości i ich opisy.

Jeśli wartość atrybutu data-allowed_parent_origin jest nieprawidłowa, inicjowanie funkcji One Tap w trybie pośredniej ramki iframe nie powiedzie się i zostanie zatrzymane.

Obsługiwane są też prefiksy z symbolami wieloznacznymi. Na przykład "https://*.example.com" pasuje do example.com i jej subdomen na wszystkich poziomach (np. news.example.com, login.news.example.com). O czym należy pamiętać, używając symboli wieloznacznych:

• Ciągi wzorców nie mogą składać się tylko z symbolu wieloznacznego i domeny najwyższego poziomu. Na przykład https://.com i https://.co.uk są nieprawidłowe, ponieważ "https://.example.com" pasuje do example.com i wszystkich jej subdomen. Użyj listy rozdzielonej przecinkami, aby reprezentować 2 różne domeny. Na przykład "https://example1.com,https://.example2.com" pasuje do domen example1.com, example2.com i subdomen example2.com.
• Domeny z symbolem wieloznacznym muszą zaczynać się od bezpiecznego schematu https://, więc domena "*.example.com" jest uznawana za nieprawidłową.

data-intermediate_iframe_close_callback

Zastępuje domyślne działanie pośredniego elementu iframe, gdy użytkownicy ręcznie zamykają logowanie jednym dotknięciem, klikając przycisk „X” w interfejsie logowania jednym dotknięciem. Działanie domyślne polega na natychmiastowym usunięciu pośredniego elementu iframe z DOM.

Pole data-intermediate_iframe_close_callback działa tylko w trybie pośredniego elementu iframe. Ma to wpływ tylko na pośredni element iframe, a nie na element iframe logowania jednym dotknięciem. Interfejs One Tap zostanie usunięty przed wywołaniem funkcji oddzwaniania.

Funkcje JavaScriptu w przestrzeni nazw nie są obsługiwane przez interfejs HTML API. Zamiast tego użyj globalnej funkcji JavaScriptu bez przestrzeni nazw. Na przykład użyj mylibCallback zamiast mylib.callback.

data-itp_support

To pole określa, czy ulepszona funkcja One Tap UX powinna być włączona w przeglądarkach obsługujących Intelligent Tracking Prevention (ITP). (wartością domyślną jest false); Więcej informacji znajdziesz w tej tabeli:

data-login_hint

Jeśli Twoja aplikacja wie z wyprzedzeniem, który użytkownik powinien się zalogować, może przekazać Google podpowiedź logowania. Jeśli się powiedzie, wybór konta zostanie pominięty. Akceptowane wartości: adres e-mail lub pole sub tokena identyfikacji.

Więcej informacji znajdziesz w dokumentacji OpenID Connect dotyczącej login_hint.

data-hd

Jeśli użytkownik ma kilka kont i powinien logować się tylko na konto Workspace, użyj tej opcji, aby podać Google wskazówkę dotyczącą nazwy domeny. Jeśli się powiedzie, konta użytkowników wyświetlane podczas wyboru konta będą ograniczone do podanej domeny. Wartość wieloznaczna: * oferuje użytkownikowi tylko konta Workspace i wyklucza konta konsumenckie (użytkownik@gmail.com) podczas wyboru konta.

Więcej informacji znajdziesz w dokumentacji OpenID Connect dotyczącej hd.

data-use_fedcm_for_prompt

Zezwalaj przeglądarce na kontrolowanie próśb o zalogowanie się użytkownika i pośredniczenie w procesie logowania między Twoją witryną a Google. Wartość domyślna to fałsz. Więcej informacji znajdziesz na stronie Migracja do FedCM.

data-use_fedcm_for_button

To pole określa, czy w Chrome (wersja M125 lub nowsza na komputerach i M128 lub nowsza na Androidzie) ma być używany interfejs przycisku FedCM. Wartość domyślna to false. Więcej informacji znajdziesz w tej tabeli:

data-button_auto_select

To pole określa, czy w przypadku procesu przycisku FedCM ma być włączona opcja automatycznego wyboru. Jeśli ta opcja jest włączona, powracający użytkownicy z aktywną sesją Google będą logowani automatycznie, bez wyświetlania prośby o wybranie konta. Wartość domyślna to false. Podczas uruchamiania akceptacji musisz wyraźnie włączyć automatyczne logowanie za pomocą przycisku. Więcej informacji znajdziesz w tej tabeli:

Element z klasą „g_id_signin”

Jeśli dodasz g_id_signin do atrybutu class elementu, element będzie renderowany jako przycisk Zaloguj się przez Google.

Na tej samej stronie możesz wyświetlać wiele przycisków Zaloguj się przez Google. Każdy przycisk może mieć własne ustawienia wizualne. Ustawienia są definiowane przez te atrybuty danych.

Atrybuty danych wizualnych

W tabeli poniżej znajdziesz listę atrybutów danych wizualnych i ich opisy:

Typy atrybutów

W poniższych sekcjach znajdziesz szczegółowe informacje o typach poszczególnych atrybutów oraz przykłady.

data-type

Typ przycisku. Wartością domyślną jest standard. Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz wszystkie dostępne typy przycisków i ich opisy:

Typ
standard
icon

data-theme

Motyw przycisku. Wartością domyślną jest outline. Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz dostępne motywy i ich opisy:

Motyw	Przykłady	Specyfikacja
outline		Wypełnienie: #FFFFFF Obrys: #747775 | 1 px | wewnątrz Czcionka: #1F1F1F | Roboto Medium | 14/20 Spersonalizowana: #1F1F1F | Roboto | Medium 12/14 | Regular 11/13
filled_blue		Wypełnienie: #0B57D0 Obrys: #OB57D0 | 1 px | wewnątrz Czcionka: #FFFFFF | Google Sans Medium | 14/20 Spersonalizowana: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
filled_black		Fill: #202124 Stroke: #OB57D0 | 1px | inside Font: #FFFFFF | Google Sans Medium | 14/20 Personalized: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
outline_dark		Wypełnienie: #131314 Obrys: #8E918F | 1 px | wewnątrz Czcionka: #FFFFFF | Google Sans Medium | 14/20 Spersonalizowana: #FFFFFF | Roboto | Medium 12/14 | Zwykła 11/13

data-size

Rozmiar przycisku. Wartością domyślną jest large. Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz dostępne rozmiary przycisków i ich opisy.

Rozmiar
large
medium
small

data-text

Tekst przycisku. Wartością domyślną jest signin_with. Nie ma wizualnych różnic w tekście przycisków ikon, które mają różne atrybuty data-text. Jedynym wyjątkiem jest sytuacja, gdy tekst jest odczytywany na potrzeby ułatwień dostępu.

Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz dostępne teksty przycisków i ich opisy:

Tekst
signin_with
signup_with
continue_with
signin

data-shape

Kształt przycisku. Wartością domyślną jest rectangular. Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz dostępne kształty przycisków i ich opisy:

Kształt
rectangular
pill
circle
square

data-logo_alignment

Wyrównanie logo Google. Wartością domyślną jest left. Ten atrybut dotyczy tylko typu przycisku standard. Więcej informacji znajdziesz w tej tabeli:

W tabeli poniżej znajdziesz dostępne wyrównania i ich opisy:

logo_alignment
left
center

data-width

Minimalna szerokość przycisku w pikselach. Maksymalna dostępna szerokość to 400 pikseli.

Więcej informacji znajdziesz w tej tabeli:

data-locale

Opcjonalnie. Wyświetlaj tekst przycisku w określonym języku. W przeciwnym razie użyj domyślnego języka konta Google lub ustawień przeglądarki użytkownika. Podczas wczytywania biblioteki dodaj do dyrektywy src parametr hl i kod języka, np. gsi/client?hl=<iso-639-code>.

Jeśli nie jest ustawiona, używane są domyślne ustawienia regionalne przeglądarki lub preferencje użytkownika sesji Google. Dlatego różni użytkownicy mogą widzieć różne wersje zlokalizowanych przycisków, które mogą mieć różne rozmiary.

Więcej informacji znajdziesz w tej tabeli:

data-click_listener

Możesz zdefiniować funkcję JavaScript, która będzie wywoływana po kliknięciu przycisku Zaloguj się przez Google, używając atrybutu data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

W tym przykładzie po kliknięciu przycisku Zaloguj się przez Google w konsoli jest rejestrowany komunikat Kliknięto przycisk Zaloguj się przez Google….

data-state

Opcjonalnie, ponieważ na tej samej stronie można renderować wiele przycisków Zaloguj się przez Google, możesz przypisać do każdego przycisku unikalny ciąg znaków. Ten sam ciąg znaków zostanie zwrócony wraz z tokenem identyfikacji, dzięki czemu możesz określić, który przycisk został kliknięty przez użytkownika, aby się zalogować.

Więcej informacji znajdziesz w tej tabeli:

Integracja po stronie serwera

Punkty końcowe po stronie serwera muszą obsługiwać te żądania HTTP POST.

Punkt końcowy modułu obsługi tokena identyfikacji

Punkt końcowy modułu obsługi tokena identyfikacji przetwarza token identyfikacji. W zależności od stanu odpowiedniego konta możesz zalogować użytkownika i przekierować go na stronę rejestracji lub na stronę łączenia kont, aby uzyskać dodatkowe informacje. Klienty MUSZĄ ignorować nierozpoznane parametry odpowiedzi.

Przykładowe żądanie wysłane do punktu końcowego logowania:

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

Żądanie HTTP POST zawiera te informacje:

dane logowania

Po zdekodowaniu token identyfikacji wygląda jak w tym przykładzie:

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 Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "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": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

Klienty MUSZĄ ignorować nierozpoznane oświadczenia JWT.

Pole sub to globalnie unikalny identyfikator konta Google. Tylko pole sub może być używane jako identyfikator użytkownika, ponieważ jest unikalne dla wszystkich kont Google i nigdy nie jest używane ponownie.

Za pomocą pól email, email_verified i hd możesz określić, czy Google hostuje adres e-mail i czy jest on autorytatywny. W przypadkach, gdy Google jest organem nadrzędnym, użytkownik jest potwierdzany jako prawowity właściciel konta.

Przypadki, w których Google jest źródłem informacji:

• email ma sufiks @gmail.com, więc jest to konto Gmail.
• Jeśli email_verified ma wartość true i ustawiono hd, jest to konto Google Workspace.

Użytkownicy mogą rejestrować konta Google bez korzystania z Gmaila lub Google Workspace. Gdy email nie zawiera sufiksu @gmail.com i nie ma hd, Google nie jest urzędem certyfikacji i do weryfikacji użytkownika zalecane jest użycie hasła lub innych metod weryfikacji. Wartość email_verified może być też prawdziwa, jeśli Google zweryfikowało użytkownika podczas tworzenia konta Google, ale od tego czasu mogła nastąpić zmiana właściciela konta e-mail innej firmy.

Pole exp pokazuje czas, po którym wygasa możliwość zweryfikowania tokena po stronie serwera. W przypadku tokena identyfikacji uzyskanego z funkcji Zaloguj się przez Google jest to 1 godzina. Musisz zweryfikować token przed upływem czasu ważności. Nie używaj exp do zarządzania sesjami. Wygasły token identyfikacji nie oznacza, że użytkownik został wylogowany. Aplikacja odpowiada za zarządzanie sesjami użytkowników.

g_csrf_token

Token stanu zapobiegający fałszowaniu. To jest token fałszowania żądań z innych witryn (CSRF) utworzony przez bibliotekę gsi/client. Wartość losowa jest uwzględniana zarówno jako plik cookie, jak i parametr żądania w treści ładunku POST. Jeśli te 2 wartości nie są zgodne podczas przetwarzania żądania na serwerze, żądanie powinno zostać uznane za nieprawidłowe.

stan

Ten parametr jest definiowany tylko wtedy, gdy użytkownik kliknie przycisk Zaloguj się przez Google, aby się zalogować, i określony jest atrybut data-state klikniętego przycisku. Wartość tego pola jest taka sama jak wartość określona w atrybucie data-state przycisku.

Na tej samej stronie można wyrenderować wiele przycisków Zaloguj się przez Google, dlatego każdemu z nich możesz przypisać unikalny ciąg znaków. Dlatego możesz użyć tego parametru state, aby określić, który przycisk został kliknięty przez użytkownika w celu zalogowania się.

Punkt końcowy modułu obsługi danych logowania hasła

Punkt końcowy modułu obsługi danych logowania w postaci hasła przetwarza dane logowania w postaci hasła pobrane przez wbudowany Credential Manager.

Żądanie HTTP POST zawiera te informacje: