Dokumentacja interfejsu Zaloguj się z użyciem interfejsu Google JavaScript API

Ta strona referencyjna zawiera opis interfejsu JavaScript API do logowania. Za pomocą tego interfejsu API możesz wyświetlać na stronach internetowych prompt One Tap lub przycisk Zaloguj się przez Google.

Metoda: google.accounts.id.initialize

Metoda google.accounts.id.initialize inicjuje klienta Zaloguj się przez Google na podstawie obiektu konfiguracji. Poniżej znajdziesz przykład kodu metody:

google.accounts.id.initialize(IdConfiguration)

W tym przykładzie kodu implementowana jest metoda google.accounts.id.initialize za pomocą funkcji onload:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

Metoda google.accounts.id.initialize tworzy instancję klienta Zaloguj się przez Google, której można użyć domyślnie we wszystkich modułach na tej samej stronie internetowej.

• Nawet jeśli na tej samej stronie internetowej używasz wielu modułów (np. One Tap, przycisku spersonalizowanego, odwołania itp.), metodę google.accounts.id.initialize musisz wywołać tylko raz.
• Jeśli wywołasz metodę google.accounts.id.initialize kilka razy, zapamiętywane i używane są tylko konfiguracje z ostatniego wywołania.

Konfiguracje są resetowane przy każdym wywołaniu metody google.accounts.id.initialize, a wszystkie kolejne metody na tej samej stronie internetowej od razu używają nowych konfiguracji.

Typ danych: IdConfiguration

W tabeli poniżej znajdziesz pola i ich opisy w przypadku typu danych IdConfiguration:

client_id

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

auto_select

To pole określa, czy token identyfikatora jest zwracany automatycznie bez interakcji z użytkownikiem, gdy istnieje tylko 1 sesja Google, która wcześniej zatwierdziła Twoją aplikację. Wartością domyślną jest false. Więcej informacji znajdziesz w tabeli poniżej:

wywołanie zwrotne

To pole to funkcja JavaScript, która obsługuje token identyfikatora zwrócony przez prompt One Tap lub wyskakujące okienko. Ten atrybut jest wymagany, jeśli używasz funkcji Google One Tap lub przycisku Zaloguj się przez Google popup w ramach interfejsu użytkownika. Więcej informacji znajdziesz w tabeli poniżej:

login_uri

Ten atrybut to identyfikator URI punktu logowania.

Wartość musi dokładnie pasować do jednego z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, który skonfigurowałeś w konsoli Google Cloud i musi być zgodny z naszymi zasadami weryfikacji identyfikatorów URI przekierowania.

Ten atrybut może zostać pominięty, jeśli bieżąca strona to strona logowania, na której dane logowania są domyślnie publikowane.

Gdy użytkownik kliknie przycisk Zaloguj się przez Google i użyje przekierowania, odpowiedź na żądanie danych logowania w formie tokena tożsamości jest przesyłana do punktu końcowego logowania.

Więcej informacji znajdziesz w tabeli poniżej:

Punkt końcowy logowania musi obsługiwać żądania POST zawierające klucz credential z wartością tokena identyfikatora w sekcji treści.

Oto przykład żądania do punktu końcowego logowania:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

native_callback

To pole to nazwa funkcji JavaScriptu, która obsługuje dane logowania z hasłem zwrócone przez natywny menedżer danych logowania przeglądarki. Więcej informacji znajdziesz w tabeli poniżej:

cancel_on_tap_outside

To pole określa, czy prośba o jeden kliknięcie ma zostać anulowana, jeśli użytkownik kliknie poza promptem. Wartością domyślną jest true. Możesz go wyłączyć, ustawiając wartość na false. Więcej informacji znajdziesz w tabeli poniżej:

prompt_parent_id

Ten atrybut ustawia identyfikator DOM elementu kontenera. Jeśli nie jest ustawiony, w prawym górnym rogu okna pojawi się prośba o jeden kliknięcie. Więcej informacji znajdziesz w tabeli poniżej:

liczba jednorazowa

To pole to losowy ciąg znaków używany przez token identyfikatora w celu zapobiegania atakom metodą powtórzenia. Więcej informacji znajdziesz w tabeli poniżej:

Długość identyfikatora Nonce jest ograniczona do maksymalnego rozmiaru tokena JWT obsługiwanego przez Twoje środowisko oraz ograniczeń rozmiaru w przypadku poszczególnych przeglądarek i serwerów HTTP.

sytuacja

To pole zmienia tekst tytułu i wiadomości w promptach One Tap. Więcej informacji znajdziesz w tabeli poniżej:

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

state_cookie_domain

Jeśli chcesz wyświetlać One Tap w domenie nadrzędnej i jej subdomenach, prześlij domenę nadrzędną do tego pola, aby użyć jednego pliku cookie ze wspólnym stanem. Więcej informacji znajdziesz w tabeli poniżej:

ux_mode

W tym polu możesz ustawić przepływ użytkownika używany przez przycisk Zaloguj się przez Google. Wartością domyślną jest popup. Ten atrybut nie ma wpływu na interfejs OneTap. Więcej informacji znajdziesz w tabeli poniżej:

W tabeli poniżej znajdziesz dostępne tryby interfejsu użytkownika i ich opisy.

allowed_parent_origin

Źródła, które mogą umieszczać pośredni element iframe. Jeśli to pole jest obecne, funkcja One Tap działa w trybie pośrednim iframe. Więcej informacji znajdziesz w tabeli poniżej:

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

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). Podczas korzystania z symboli wieloznacznych należy pamiętać o następujących kwestiach:

• Ciągi wzorca 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. Jak wspomniano powyżej, "https://.example.com"jest zgodne z example.com i jego subdomenami. Możesz też użyć tablicy, 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 wieloznaczeniowym muszą zaczynać się od bezpiecznego schematu https://, dlatego "*.example.com" jest uważana za nieprawidłową.

Jeśli wartość pola allowed_parent_origin jest nieprawidłowa, inicjalizacja trybu pośredniego iframe usługi One Tap zakończy się niepowodzeniem i zostanie zatrzymana.

intermediate_iframe_close_callback

Zastępuje domyślne zachowanie iframe pośredniego, gdy użytkownicy ręcznie zamykają One Tap, klikając przycisk „X” w interfejsie One Tap. Domyślnie iframe pośredniczący jest natychmiast usuwany z DOM.

Pole intermediate_iframe_close_callback ma zastosowanie tylko w trybie pośrednim iframe. Ma to wpływ tylko na pośredni tag iframe, a nie na tag iframe One Tap. Interfejs One Tap jest usuwany przed wywołaniem połączenia zwrotnego.

itp_support

To pole określa, czy ulepszona wersja interfejsu One Tap powinna być włączona w przeglądarkach obsługujących inteligentną ochronę przed śledzeniem (ITP). (wartością domyślną jest false); Więcej informacji znajdziesz w tabeli poniżej:

login_hint

Jeśli aplikacja wie z wyprzedzeniem, który użytkownik powinien się zalogować, może przekazać Google podpowiedź logowania. Jeśli się powiedzie, pominiesz wybór konta. Akceptowane wartości to adres e-mail lub wartość pola sub w tokenie identyfikacyjnym.

Więcej informacji znajdziesz w polu login_hint w dokumentacji OpenID Connect.

HD

Jeśli użytkownik ma kilka kont i powinien logować się tylko na konto Workspace, użyj tego polecenia, aby podać Google podpowiedź nazwy domeny. Jeśli się uda, konta użytkowników wyświetlane podczas wyboru konta będą ograniczone do podanej domeny. Wartość z symbolem wieloznacznym: * oferuje użytkownikowi tylko konta Workspace i wyklucza konta użytkowników (user@gmail.com) podczas wyboru konta.

Więcej informacji znajdziesz w polu hd w dokumentacji OpenID Connect.

use_fedcm_for_prompt

Zezwalaj przeglądarce na kontrolowanie promptów logowania użytkownika i na 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.

Metoda: google.accounts.id.prompt

Po wywołaniu metody initialize() metoda google.accounts.id.prompt wyświetla prompt One Tap lub menedżera danych logowania w przeglądarce. Poniżej znajdziesz przykładowy kod tej metody:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

Zwykle metoda prompt() jest wywoływana podczas wczytywania strony. Ze względu na stan sesji i ustawienia użytkownika po stronie Google interfejs promptu One Tap może się nie wyświetlać. Aby otrzymywać powiadomienia o stanie interfejsu w różnych momentach, prześlij funkcję, która będzie wysyłać powiadomienia o stanie interfejsu.

Powiadomienia są wysyłane w tych momentach:

• Moment wyświetlania: następuje po wywołaniu metody prompt(). Powiadomienie zawiera wartość logiczną wskazującą, czy interfejs użytkownika jest wyświetlany, czy nie.

• Pominięcie momentu: występuje, gdy prośba o użycie funkcji One Tap została zamknięta automatycznie lub ręcznie albo gdy Google nie może wydać danych logowania, np. gdy wybrana sesja została wylogowana z Google.

  W takich przypadkach zalecamy przejście do następnego dostawcy tożsamości, jeśli taki istnieje.

• Moment odrzucenia: występuje, gdy Google pomyślnie odzyska dane logowania lub użytkownik chce przerwać proces ich pobierania. Gdy na przykład użytkownik zacznie wpisywać nazwę użytkownika i hasło w oknie logowania, możesz wywołać metodę google.accounts.id.cancel(), aby zamknąć prompt One Tap i wywołać moment odrzucenia.

Ten przykładowy kod wdraża pominięcie:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

Typ danych: PromptMomentNotification

W tabeli poniżej znajdziesz metody i opis typu danych PromptMomentNotification:

Typ danych: CredentialResponse

Gdy wywoływana jest funkcja callback, jako parametr przekazywany jest obiekt CredentialResponse. Tabela poniżej zawiera listę pól zawartych w obiekcie odpowiedzi z danymi logowania:

certyfikat

To pole to ciąg znaków tokena ID zakodowanego w formacie Base64 w postaci tokena sieciowego JSON (JWT).

Po odkodowaniu token JWT wygląda tak:

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 GSuite email address
  "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": "Elisa",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

Pole sub to globalnie unikalny identyfikator konta Google. Tylko pole sub należy używać jako identyfikator użytkownika, ponieważ jest on niepowtarzalny wśród wszystkich kont Google i nigdy nie jest używany ponownie.

Za pomocą pól email, email_verified i hd możesz określić, czy Google hostuje adres e-mail i jest autorytatywną domeną. W przypadkach, gdy Google jest autorytatywnym źródłem informacji, potwierdzamy, że użytkownik jest prawowitym właścicielem konta.

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

• email ma sufiks @gmail.com, co oznacza, że jest to konto Gmail.
• Jeśli email_verified ma wartość true, a hd jest ustawiona, jest to konto Google Workspace.

Użytkownicy mogą rejestrować się na konta Google bez korzystania z Gmaila lub Google Workspace. Jeśli email nie zawiera sufiksu @gmail.com, a hd jest nieobecne, Google nie jest wiarygodne i do weryfikacji użytkownika zaleca się użycie hasła lub innej metody weryfikacji. email_verfied może być również prawdziwe, ponieważ Google zweryfikowało użytkownika podczas tworzenia konta Google, ale własność konta e-mail innej firmy mogła się od tego czasu zmienić.

Pole exp zawiera czas, w którym musisz zweryfikować token po stronie serwera. Czas ważności tokena identyfikacyjnego uzyskanego z Logowania przez Google wynosi 1 godzinę. Musisz zweryfikować token przed upływem terminu ważności. Nie używaj funkcji exp do zarządzania sesjami. Wygasły token identyfikacyjny nie oznacza, że użytkownik jest wylogowany. Twoja aplikacja odpowiada za zarządzanie sesjami użytkowników.

select_by

W tabeli poniżej znajdziesz możliwe wartości pola select_by. Wartość jest określana na podstawie typu przycisku oraz stanu sesji i zgody użytkownika.

• Użytkownik nacisnął przycisk „Jedno dotknięcie” lub „Zaloguj się przez Google” albo użył procesu automatycznego logowania bez dotykania ekranu.

• znaleziono istniejące konto, albo użytkownik wybrał i zalogował się na konto Google, aby utworzyć nową sesję.

• Zanim udostępnisz aplikacji dane logowania do tokena identyfikacyjnego, użytkownik:

  • nacisnął przycisk „Potwierdź”, aby wyrazić zgodę na udostępnienie danych logowania, lub
  • wcześniej wyraził(-a) zgodę i wybrał(-a) konto Google za pomocą opcji „Wybierz konto”.

Wartość tego pola jest ustawiona na jeden z tych typów:

stan

To pole jest zdefiniowane tylko wtedy, gdy użytkownik kliknie przycisk Zaloguj się przez Google, a atrybut state tego przycisku jest określony. Wartość tego pola jest taka sama jak wartość podana w atrybucie state przycisku.

Na tej samej stronie może być wyświetlonych wiele przycisków logowania się przez Google, dlatego możesz przypisać do każdego z nich unikalny ciąg znaków. Dlatego możesz użyć tego pola state, aby określić, który przycisk kliknął użytkownik, aby się zalogować.

Metoda: google.accounts.id.renderButton

Metoda google.accounts.id.renderButton renderuje przycisk Zaloguj się przez Google na stronach internetowych.

Poniżej znajdziesz przykładowy kod tej metody:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

Typ danych: GsiButtonConfiguration

W tabeli poniżej znajdziesz pola i opisy typu danych GsiButtonConfiguration:

Typy atrybutów

W kolejnych sekcjach znajdziesz szczegółowe informacje o typie każdego atrybutu oraz przykład.

typ

Typ przycisku. Wartością domyślną jest standard.

Więcej informacji znajdziesz w tabeli poniżej:

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

Typ
standard
icon

motyw

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

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

Motyw
outline
filled_blue
filled_black

rozmiar

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

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

Rozmiar
large
medium
small

tekst

Tekst przycisku. Wartością domyślną jest signin_with. Tekst przycisków z ikonami, które mają różne atrybuty text, nie różni się wizualnie. Jedynym wyjątkiem jest odczytywanie tekstu na potrzeby czytnika ekranu.

Więcej informacji znajdziesz w tabeli poniżej:

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

Tekst
signin_with
signup_with
continue_with
signin

kształt

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

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

Kształt
rectangular
pill
circle
square

logo_alignment

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

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

logo_alignment
left
center

szerokość

Minimalna szerokość przycisku (w pikselach). Maksymalna szerokość to 400 pikseli.

Więcej informacji znajdziesz w tabeli poniżej:

locale

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

Jeśli nie jest ona ustawiona, używana jest domyślna lokalizacja przeglądarki lub ustawienie użytkownika sesji Google. Dlatego różni użytkownicy mogą widzieć różne wersje spersonalizowanych przycisków, prawdopodobnie o różnych rozmiarach.

Więcej informacji znajdziesz w tabeli poniżej:

click_listener

Za pomocą atrybutu click_listener możesz zdefiniować funkcję JavaScript, która zostanie wywołana po kliknięciu przycisku Zaloguj się przez Google.

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }
  

W tym przykładzie po kliknięciu przycisku Zaloguj się przez Google w konsoli odnotowywana jest wiadomość Przycisk Zaloguj się przez Google został kliknięty.

stan

Opcjonalnie, ponieważ na tej samej stronie może być wyświetlonych kilka przycisków „Zaloguj się przez Google”, możesz przypisać do każdego z nich unikalny ciąg znaków. Ten sam ciąg zwracany jest razem z tokenem identyfikacyjnym, dzięki czemu możesz określić, który przycisk użytkownik kliknął, aby się zalogować.

Więcej informacji znajdziesz w tabeli poniżej:

Typ danych: dane logowania

Gdy wywoływana jest funkcja native_callback, jako parametr przekazywany jest obiekt Credential. W tabeli poniżej wymieniono pola zawarte w obiekcie:

Metoda: google.accounts.id.disableAutoSelect

Gdy użytkownik wyloguje się z Twojej witryny, musisz wywołać metodę google.accounts.id.disableAutoSelect, aby zapisać stan w plikach cookie. Zapobiega to pętli bez wyjścia w interfejsie. Oto fragment kodu tej metody:

google.accounts.id.disableAutoSelect()

W tym przykładzie kodu metoda google.accounts.id.disableAutoSelect jest implementowana za pomocą funkcji onSignout():

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

Metoda: google.accounts.id.storeCredential

Ta metoda jest obudową metody store() z natywnego interfejsu API menedżera danych logowania przeglądarki. Dlatego można go używać tylko do przechowywania danych logowania. Poniżej znajdziesz przykładowy kod tej metody:

google.accounts.id.storeCredential(Credential, callback)

W tym przykładzie kodu metoda google.accounts.id.storeCredential jest implementowana za pomocą funkcji onSignIn():

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

Metoda: google.accounts.id.cancel

Możesz anulować proces One Tap, jeśli usuniesz prompt z DOM strony powierzającej. Operacja anulowania jest ignorowana, jeśli dane logowania są już wybrane. Zapoznaj się z tym przykładem kodu metody:

google.accounts.id.cancel()

W tym przykładzie kodu implementowana jest metoda google.accounts.id.cancel() za pomocą funkcji onNextButtonClicked():

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

Callback funkcji wczytywania biblioteki: onGoogleLibraryLoad

Możesz zarejestrować wywołanie zwrotne onGoogleLibraryLoad. Jest ona powiadamiana po załadowaniu biblioteki JavaScript Sign-In with Google:

window.onGoogleLibraryLoad = () => {
    ...
};

Ten wywołanie zwrotne to tylko skrót do wywołania zwrotnego window.onload. Nie ma różnic w zachowaniu.

Poniższy przykład kodu implementuje wywołanie zwrotne onGoogleLibraryLoad:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

Metoda: google.accounts.id.revoke

Metoda google.accounts.id.revoke cofa uprawnienia OAuth używane do udostępniania tokena identyfikatora określonego użytkownika. Zapoznaj się z tym fragmentem kodu metody: javascript google.accounts.id.revoke(login_hint, callback)

Poniższy przykładowy kod pokazuje, jak używać metody revoke z identyfikatorem.

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

Typ danych: RevocationResponse

Gdy wywoływana jest funkcja callback, jako parametr przekazywany jest obiekt RevocationResponse. W tabeli poniżej znajdziesz listę pól zawartych w obiekcie odpowiedzi na prośbę o odstąpienie od umowy:

udało się

To pole to wartość logiczna ustawiona na „true” (prawda), jeśli wywołanie metody revoke zakończyło się powodzeniem, lub na „false” (fałsz), jeśli zakończyło się niepowodzeniem.

błąd

To pole jest wartością ciągu znaków i zawiera szczegółowy komunikat o błędzie, jeśli wywołanie metody revoke zakończyło się niepowodzeniem. W przeciwnym razie jest nieokreślone.