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

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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ładowy kod 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ętane i użyte zostaną 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 natychmiast 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żesz 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:

callback

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 trybu UX Google One Tap lub przycisku Zaloguj się przez Google popup. 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. Musi on być zgodny z naszymi zasadami sprawdzania identyfikatorów URI przekierowania.

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

Gdy użytkownik kliknie przycisk Zaloguj się przez Google i użyje przekierowania, odpowiedź na dane logowania w formie tokena tożsamości zostanie przesłana do punktu 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 JavaScript, która obsługuje hasło zwracane przez wbudowany menedżer danych logowania w przeglądarce. 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 nią. 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ść nonce jest ograniczona do maksymalnego rozmiaru tokena JWT obsługiwanego przez środowisko oraz ograniczeń rozmiaru w poszczególnych przeglądarkach i serwerach HTTP.

kontekst

To pole zmienia tekst tytułu i wiadomości wyświetlane w prośbie o jeden klik. Nie ma ono wpływu na przeglądarki ITP. Domyślna wartość to signin.

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, ponieważ "https://.example.com" pasuje do example.com i wszystkich jego subdomen. Użyj listy oddzielonej przecinkami, aby reprezentować 2 różne domeny. Na przykład: "https://example1.com,https://.example2.com" pasuje do domen example1.com i example2.com oraz subdomen domeny example2.com
• Domeny z symbolem wieloznaczeniowym muszą zaczynać się od bezpiecznego schematu https://, więc "*.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, pomijanie wyboru 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 operacja się powiedzie, 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

Zezwalanie przeglądarce na kontrolowanie promptów logowania użytkownika i zarządzanie procesem logowania między Twoją witryną a Google. Wartość domyślna to fałsz. Więcej informacji znajdziesz na stronie Migracja na FedCM.

use_fedcm_for_button

To pole określa, czy w Chrome (na komputerach z systemem operacyjnym od wersji M125 i nowszych oraz na urządzeniach z Androidem od wersji M128 i nowszych) ma być używany interfejs przycisku FedCM. Wartość domyślna to false. Więcej informacji znajdziesz w tabeli poniżej:

button_auto_select

To pole określa, czy włączyć opcję automatycznego wybierania w przypadku procesu wyboru przycisku w Federacji. Jeśli ta opcja jest włączona, powracający użytkownicy z aktywną sesją Google będą automatycznie logowani, omijając prośbę o wybór konta. Domyślnie false. Podczas uruchamiania opcji włączania musisz wyraźnie włączyć automatyczne logowanie. Więcej informacji znajdziesz w tabeli poniżej:

Metoda: google.accounts.id.prompt

Po wywołaniu metody google.accounts.id.prompt wyświetli się prompt One Tap lub wbudowany w przeglądarkę menedżer danych logowania.initialize() 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ę, aby otrzymywać 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.

• Pominięcie momentu: występuje, gdy prośba o jeden klik jest zamknięta przez automatyczne anulowanie, ręczne anulowanie lub gdy Google nie może wydać danych logowania, na przykład 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 „Jeden kliknięciem” 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 opisy 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:

dane logowania

To pole to ciąg znaków tokena ID w postaci zakodowanego w formacie base64 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 autorytatywnym ź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 ustawiony, oznacza to, że 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 przyrostka @gmail.com, a hd jest nieobecny, Google nie jest wiarygodne i zaleca się weryfikację użytkownika za pomocą 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. W przypadku tokena identyfikacyjnego uzyskanego z Logowania przez Google wynosi on 1 godzinę. Musisz potwierdzić 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, sesji i stanu zgody.

• Użytkownik nacisnął przycisk „Jedno dotknięcie” lub „Zaloguj się przez Google” albo użył automatycznego procesu 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 dane logowania w tokenie identyfikacyjnym aplikacji, użytkownik:

  • nacisnąć przycisk „Potwierdź”, aby wyrazić zgodę na udostępnienie danych logowania,
  • 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ść określona 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 wyświetla 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 czytników 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 przycisku typu 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świetl tekst przycisku w określonym języku. W przeciwnym razie zostanie użyty domyślny język ustawiony na koncie Google użytkownika lub w ustawieniach 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żywane są domyślne ustawienia języka przeglądarki lub preferencje 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 znaków zostanie zwrócony wraz 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. Tabela poniżej zawiera listę pól zawartych 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() wbudowanego w przeglądarkę interfejsu API menedżera danych logowania. 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. Poniżej znajdziesz przykładowy kod tej 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 wczytaniu biblioteki JavaScript SignInWithGoogle:

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 wdraża 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 unieważnia uprawnienia OAuth używane do udostępniania tokena identyfikującego 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 rezygnacji:

udane

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.