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. przycisku One Tap, przycisku spersonalizowanego, odwołania itp.), metodę google.accounts.id.initialize wystarczy wywołać tylko raz.
• Jeśli wywołasz metodę google.accounts.id.initialize wiele 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 korzystają z 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 użytkownika w przypadku wystąpienia tylko jednej sesji Google, która 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 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 i musi 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.

Odpowiedź na żądanie danych logowania w formie tokena tożsamości jest wysyłana do punktu logowania, gdy użytkownik kliknie przycisk Zaloguj się przez Google i użyje trybu przekierowania UX.

Więcej informacji znajdziesz w tej tabeli:

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 zawiera nazwę funkcji JavaScript, która obsługuje hasła zwracane przez natywny menedżer danych logowania w przeglądarce. Więcej informacji znajdziesz w tej tabeli:

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żna ją wyłączyć, ustawiając wartość na false. Więcej informacji znajdziesz w tej tabeli:

prompt_parent_id

Ten atrybut ustawia identyfikator DOM elementu kontenera. Jeśli nie jest ustawiona, w prawym górnym rogu okna wyświetla się prompt jednym dotknięciem. 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 Twoje środowisko oraz ograniczeń rozmiaru w przypadku poszczególnych przeglądarek i serwerów HTTP.

sytuacja

W tym polu zmienia się tytuł i tekst wiadomości wyświetlanych w prompcie jednym dotknięciem. 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ść domyślna to popup. Ten atrybut nie ma wpływu na interfejs użytkownika w ramach usługi One-Tap. Więcej informacji znajdziesz w tabeli poniżej:

Tabela poniżej zawiera listę dostępnych trybów 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 tej tabeli:

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). Co należy pamiętać o użyciu symboli wieloznacznych:

• 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 w ramce. Ma to wpływ tylko na pośredni tag iframe, a nie na tag iframe One Tap. Interfejs One Tap zostaje usunięty przed wywołaniem zwrotnym.

itp_support

To pole określa, czy uaktualniony UX One Tap powinien być włączony w przeglądarkach, które obsługują inteligentne zapobieganie śledzeniu (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

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

enable_redirect_uri_validation

Włącz przekierowanie przycisku zgodnie z regułami sprawdzania identyfikatorów URI przekierowania.

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 natywności przeglądarki. 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: ta sytuacja ma miejsce, gdy Google pobierze dane logowania lub użytkownik chce zatrzymać proces pobierania danych logowania. 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. W tabeli poniżej znajdziesz listę pól zawartych w obiekcie odpowiedzi z danymi logowania:

certyfikat

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. Nie używaj adresu e-mail jako identyfikatora, ponieważ konto Google może mieć w różnych momentach wiele powiązanych adresów e-mail.

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 wiarygodne, użytkownik jest uznawany za prawdziwego właściciela 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 ustawione, 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 też mieć wartość prawda, ponieważ firma Google wstępnie zweryfikowała użytkownika podczas tworzenia konta Google, jednak własność zewnętrznego konta e-mail mogła się później zmienić.

Pole exp pokazuje okres ważności, po którym możesz zweryfikować token po stronie serwera. W przypadku tokena tożsamości uzyskanego z funkcji Zaloguj się przez Google zajmuje to 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. Aplikacja odpowiada za zarządzanie sesjami użytkowników.

select_by

W tabeli poniżej znajdziesz możliwe wartości pola select_by. Do ustawienia wartości służy typ przycisku wraz z sesją i stanem zgody.

• Użytkownik nacisnął przycisk „Jedno dotknięcie” lub „Zaloguj się przez Google” albo skorzystał z automatycznego logowania bezdotykowego.

• 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, aby się zalogować, i jeśli atrybut state tego przycisku został określony. Wartość w tym polu jest taka sama jak wartość podana w atrybucie state przycisku.

Na tej samej stronie może być wyświetlanych wiele przycisków Zaloguj się przez Google, więc każdemu z nich możesz przypisać 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 tej tabeli:

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 w celu zapewnienia dostępności dla osób z niepełnosprawnością wzroku.

Więcej informacji znajdziesz w tej tabeli:

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 tej tabeli:

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 ustawiony, 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 tej tabeli:

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 wiele przycisków „Zaloguj się przez Google”, możesz przypisać do każdego z nich unikalny ciąg znaków. Wraz z tokenem identyfikatora zostanie zwrócony ten sam ciąg znaków, dzięki czemu możesz określić, który użytkownik kliknął przycisk, aby się zalogować.

Więcej informacji znajdziesz w tabeli poniżej:

Typ danych: dane logowania

Po wywołaniu funkcji native_callback jako parametr przekazywany jest obiekt Credential. Poniższa tabela 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() z rodzinnego interfejsu API menedżera danych logowania w przeglądarce. 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, która korzysta z usługi. Jeśli dane logowania zostały już wybrane, operacja anulowania jest ignorowana. Poniżej znajdziesz przykładowy kod tej metody:

google.accounts.id.cancel()

Ten przykładowy kod implementuje metodę google.accounts.id.cancel() z funkcją onNextButtonClicked():

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

Callback wczytywania biblioteki: onGoogleLibraryLoad

Możesz zarejestrować wywołanie zwrotne onGoogleLibraryLoad. Po wczytaniu biblioteki JavaScript Zaloguj się przez Google pojawia się powiadomienie:

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

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

Ten przykładowy kod 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 unieważnia uprawnienia OAuth używane do udostępniania tokena identyfikującego określonego użytkownika. Wyświetl ten fragment 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 znajdziesz listę pól zawartych w obiekcie odpowiedzi na prośbę o odstąpienie od umowy:

udało się

To pole zawiera wartość logiczną „true” (prawda), jeśli wywołanie metody unieważnienia zakończyło się sukcesem, lub „false” (fałsz) w przypadku niepowodzenia.

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.