W tym artykule znajdziesz opis metod i atrybutów klienta JavaScript, które będą służyć do implementowania Logowania przez Google w Twoich aplikacjach internetowych.
Jeśli napotkasz problemy z biblioteką, zgłoś je w naszym repozytorium GitHub.
Konfiguracja uwierzytelniania
Wczytaj bibliotekę platformy Google API, aby utworzyć obiekt gapi
:
<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>
Po wczytaniu biblioteki platformy wczytaj bibliotekę auth2
:
function init() {
gapi.load('auth2', function() {
/* Ready. Make a call to gapi.auth2.init or some other API */
});
}
gapi.auth2.init(params)
Inicjuje obiekt GoogleAuth
. Musisz wywołać tę metodę przed wywołaniem metod aplikacji gapi.auth2.GoogleAuth
.
Podczas inicjowania obiektu GoogleAuth
konfigurujesz go za pomocą identyfikatora klienta OAuth 2.0 i wszelkich dodatkowych opcji, które chcesz określić. Następnie, jeśli użytkownik jest już zalogowany, obiekt GoogleAuth
przywraca stan logowania użytkownika z poprzedniej sesji.
Argumenty | |
---|---|
params |
Obiekt zawierający pary klucz-wartość danych konfiguracyjnych klienta. W sekcji gapi.auth2.ClientConfig znajdziesz różne właściwości, które można skonfigurować. Na przykład: { client_id: 'CLIENT_ID.apps.googleusercontent.com' } |
Zwraca | |
---|---|
gapi.auth2.GoogleAuth |
Obiekt gapi.auth2.GoogleAuth . Użyj metody then(), aby uzyskać obietnicę rozwiązaną po zakończeniu inicjowania obiektu gapi.auth2.GoogleAuth .
|
GoogleAuth.then(onInit, onError)
Wywołuje funkcję onInit po pełnym zainicjowaniu obiektu GoogleAuth
. Jeśli podczas inicjowania wystąpi błąd (może się tak dziać w starych nieobsługiwanych przeglądarkach), zamiast tego wywołana będzie funkcja onError.
Argumenty | |
---|---|
onInit |
Funkcja, która została wywołana z obiektem GoogleAuth po pełnym zainicjowaniu.
|
onError |
Funkcja, która została wywołana z obiektem zawierającym właściwość error , jeśli nie udało się zainicjować funkcji GoogleAuth .
|
Zwraca | |
---|---|
Obietnica | Promise , który jest realizowany po zakończeniu funkcji onInit lub odrzucany, jeśli wystąpił błąd inicjowania. Zwraca ona wartość zwróconą przez funkcję onInit, jeśli taka istnieje. |
Kody błędów
idpiframe_initialization_failed
- Nie udało się zainicjować wymaganego elementu iframe od Google na przykład z powodu nieobsługiwanego środowiska. Właściwość
details
zawiera więcej informacji o wykrytym błędzie.
gapi.auth2.ClientConfig
Interfejs reprezentujący różne parametry konfiguracji metody gapi.auth2.init
.
Parametry | ||
---|---|---|
client_id |
string |
Wymagany. Identyfikator klienta aplikacji znaleziony i utworzony w Google Developers Console. |
cookie_policy |
string |
Domeny, dla których są tworzone pliki cookie używane do logowania. Może to być identyfikator URI, single_host_origin lub none . Jeśli nie określono inaczej, domyślnie jest to single_host_origin . |
scope |
string |
Zakresy, których dotyczy żądanie, w postaci ciągu rozdzielanego spacjami. Opcjonalne, jeśli pole fetch_basic_profile nie ma wartości Fałsz. |
fetch_basic_profile |
boolean |
Pobiera podstawowe informacje profilowe użytkowników po zalogowaniu. Dodaje „profile”, „e-mail” i „openid” do żądanych zakresów. Wartość „prawda”, jeśli nie określono inaczej |
hosted_domain |
string |
Domena G Suite, do której użytkownicy muszą należeć, aby się zalogować. Ten identyfikator może być zmieniany przez klientów, dlatego pamiętaj, aby zweryfikować usługę domeny hostowanej dla zwróconego użytkownika. Użyj GoogleUser.getHostDomain() w kliencie i deklaracji hd w tokenie identyfikatora na serwerze, aby potwierdzić własność domeny.
|
ux_mode |
string |
Tryb UX używany podczas logowania. Domyślnie będzie on uruchamiany w wyskakującym okienku. Prawidłowe wartości to popup i redirect . |
redirect_uri |
string |
Jeśli używasz parametru ux_mode='redirect' , możesz zastąpić domyślny redirect_uri , który będzie używany na końcu procedury uzyskiwania zgody. Domyślny redirect_uri to obecny URL usunięty z parametrów zapytania i fragment kodu skrótu.
|
plugin_name |
string |
Opcjonalnie. Jeśli ta wartość jest ustawiona, nowe identyfikatory klienta utworzone przed 29 lipca 2022 r. mogą korzystać ze starszej biblioteki Google Platform.
Domyślnie nowo utworzone identyfikatory klientów nie mogą korzystać z biblioteki platformy. Zamiast tego muszą używać nowszej biblioteki usług Google Identity. Możesz wybrać dowolną wartość. Zalecamy nazwę opisową, taką jak nazwa produktu lub wtyczki, aby ułatwić identyfikację.
Przykład: plugin_name: 'YOUR_STRING_HERE'
|
Uwierzytelnianie
GoogleAuth
to klasa samotna, która udostępnia metody umożliwiające użytkownikowi zalogowanie się za pomocą konta Google, sprawdzenie jego bieżącego stanu zalogowania się, pobranie określonych danych z profilu Google użytkownika, wysłanie prośby o przyznanie dodatkowych zakresów oraz wylogowanie się z bieżącego konta.
gapi.auth2.getAuthInstance()
Zwraca obiekt GoogleAuth
. Przed wywołaniem tej metody musisz zainicjować obiekt GoogleAuth
za pomocą metody gapi.auth2.init()
.
Zwraca | |
---|---|
gapi.auth2.GoogleAuth |
Obiekt gapi.auth2.GoogleAuth . Używaj tego obiektu do wywoływania metod obiektu gapi.auth2.GoogleAuth .
|
GoogleAuth.isSignedIn.get()
Wskazuje, czy obecny użytkownik jest obecnie zalogowany.
Zwraca | |
---|---|
Wartość logiczna |
true , gdy użytkownik jest zalogowany, lub false , jeśli użytkownik jest wylogowany, lub obiekt GoogleAuth nie został zainicjowany.
|
GoogleAuth.isSignedIn.listen(słuchacz)
Wykrywaj zmiany stanu logowania bieżącego użytkownika.
Argumenty | |
---|---|
listener |
Funkcja przyjmująca wartość logiczną. listen() przekazuje do tej funkcji atrybut true , gdy użytkownik się loguje, i false , gdy użytkownik się wyloguje.
|
GoogleAuth.signIn()
Loguje użytkownika z opcjami określonymi na gapi.auth2.init()
.
Zwraca | |
---|---|
Obietnica | Promise , który jest wypełniany po wystąpieniu instancji GoogleUser , gdy użytkownik uwierzytelni się i przyzna wymagane zakresy lub zostanie odrzucony z obiektem zawierającym właściwość error , jeśli wystąpił błąd (poniżej znajdziesz kody błędów). |
Kody błędów
Zobacz GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Loguje się przy użyciu określonych opcji.
Argumenty | |
---|---|
options |
Wykonaj jedną z tych czynności:
|
Zwraca | |
---|---|
Obietnica | Promise , który jest wypełniany po wystąpieniu instancji GoogleUser , gdy użytkownik uwierzytelni się i przyzna wymagane zakresy lub zostanie odrzucony z obiektem zawierającym właściwość error , jeśli wystąpił błąd (poniżej znajdziesz kody błędów). |
Kody błędów
popup_closed_by_user
- Użytkownik zamknął wyskakujące okienko, zanim zakończył proces logowania.
access_denied
- Użytkownik odmówił przyznania wymaganych zakresów.
immediate_failed
- Żadnego użytkownika nie można wybrać automatycznie bez pytania użytkownika o zgodę na przetwarzanie danych osobowych. Podczas używania
signIn
z użyciem opcjiprompt: 'none'
wystąpił błąd. Ta opcja nie powinna być wymagana, ponieważgapi.auth2.init
zaloguje się automatycznie, jeśli użytkownik zalogował się wcześniej podczas poprzedniej sesji.
gapi.auth2.SignInOptions
Interfejs reprezentujący różne parametry konfiguracji metody GoogleAuth.signIn(options)
.
Parametry | ||
---|---|---|
prompt |
string |
Wymusza określony tryb procesu uzyskiwania zgody. Opcjonalnie. Możliwe wartości:
|
scope |
string |
Zakresy, które mają zostać przesłane w postaci ciągu rozdzielanego spacjami, oprócz zakresów zdefiniowanych w parametrach gapi.auth2.init . Opcjonalne, jeśli fetch_basic_profile nie ma wartości Fałsz.
|
ux_mode |
string |
Tryb UX używany podczas logowania. Domyślnie będzie on uruchamiany w wyskakującym okienku. Prawidłowe wartości to popup i redirect . |
redirect_uri |
string |
Jeśli używasz parametru ux_mode='redirect' , ten parametr pozwala zastąpić domyślny redirect_uri , który będzie używany na końcu procesu uzyskiwania zgody. Domyślny redirect_uri to obecny URL usunięty z parametrów zapytania i fragmentu z krzyżykiem.
|
GoogleAuth.signOut()
Wylogowuje z konta bieżące konto.
Zwraca | |
---|---|
Obietnica | Promise , który jest realizowany, gdy użytkownik jest wylogowany. |
GoogleAuth.disconnect()
Anuluje wszystkie zakresy przydzielone przez użytkownika.
GoogleAuth.grantOfflineAccess(options)
Uzyskaj od użytkownika uprawnienia dostępu do określonych zakresów w trybie offline.
Argumenty | |
---|---|
options |
Obiekt gapi.auth2.OfflineAccessOptions zawierający pary klucz-wartość parametrów. Przykład: { scope: 'profile email' } |
Zwraca | |
---|---|
Obietnica | Promise , który jest wypełniany, gdy użytkownik przyznaje żądane zakresy, przekazując obiekt zawierający kod autoryzacji do modułu obsługi realizacji Promise .
Przykład: auth2.grantOfflineAccess().then(function(resp) { var auth_code = resp.code; }); |
Kody błędów
popup_closed_by_user
- Użytkownik zamknął wyskakujące okienko, zanim dokończy proces wyrażania zgody.
access_denied
- Użytkownik odmówił przyznania wymaganych zakresów.
immediate_failed
- Żadnego użytkownika nie można wybrać automatycznie bez pytania użytkownika o zgodę na przetwarzanie danych osobowych. Podczas używania
signIn
z użyciem opcjiprompt: 'none'
wystąpił błąd. Ta opcja nie powinna być wymagana, ponieważgapi.auth2.init
zaloguje się automatycznie, jeśli użytkownik zalogował się wcześniej podczas poprzedniej sesji.
gapi.auth2.Opcje dostępu offline
Interfejs reprezentujący różne parametry konfiguracji metody GoogleAuth.grantOfflineAccess(options)
.
Parametry | ||
---|---|---|
prompt |
string |
Wymusza określony tryb procesu uzyskiwania zgody. Opcjonalnie. Możliwe wartości:
|
scope |
string |
Zakresy, które mają zostać przesłane w postaci ciągu rozdzielanego spacjami, oprócz zakresów zdefiniowanych w parametrach gapi.auth2.init . Opcjonalne, jeśli fetch_basic_profile nie ma wartości Fałsz.
|
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
Dołącza procedurę logowania do modułu obsługi kliknięcia określonego kontenera.
Argumenty | |
---|---|
container | Identyfikator lub odniesienie do elementu div , do którego ma być dołączany moduł obsługi kliknięć. |
options | Obiekt zawierający pary klucz-wartość parametrów. Zobacz GoogleAuth.signIn(). |
onsuccess | Funkcja, która ma zostać wywołana po zakończeniu logowania. |
onfailure | Funkcja, która ma zostać wywołana w przypadku nieudanego logowania. |
Użytkownicy
Obiekt GoogleUser
reprezentuje jedno konto użytkownika.
Obiekty GoogleUser
zwykle uzyskuje się przez wywołanie GoogleAuth.currentUser.get().
GoogleAuth.currentUser.get()
Zwraca obiekt GoogleUser
reprezentujący bieżącego użytkownika. Pamiętaj, że w nowo zainicjowanej instancji GoogleAuth
bieżący użytkownik nie został skonfigurowany. Aby uzyskać zainicjowaną instancję GoogleAuth
, użyj metody currentUser.listen()
lub GoogleAuth.then()
.
Zwraca | |
---|---|
GoogleUser |
Bieżący użytkownik |
GoogleAuth.currentUser.listen(listener)
Wykrywaj zmiany w bieżącym użytkowniku.
Argumenty | |
---|---|
listener |
Funkcja przyjmująca parametr GoogleUser .
listen przekazuje tę funkcję do instancji GoogleUser przy każdej zmianie, która modyfikuje currentUser .
|
GoogleUser.getId()
Pobierz unikalny ciąg identyfikatora użytkownika.
Zwraca | |
---|---|
Ciąg znaków | Unikalny identyfikator użytkownika. |
GoogleUser.isSignedIn()
Zwraca wartość „prawda”, jeśli użytkownik jest zalogowany.
Zwraca | |
---|---|
Wartość logiczna | Prawda, jeśli użytkownik jest zalogowany |
GoogleUser.getHostDomain()
Uzyskaj domenę G Suite użytkownika, jeśli zalogował się na konto G Suite.
Zwraca | |
---|---|
Ciąg znaków | Domena G Suite użytkownika |
GoogleUser.getGrantedScopes()
Pobierz zakresy, które użytkownik przyznał jako ciąg rozdzielany spacjami.
Zwraca | |
---|---|
Ciąg znaków | Zakresy przyznane przez użytkownika |
GoogleUser.getBasicProfile()
Uzyskaj podstawowe informacje na temat użytkownika.
Zwraca | |
---|---|
gapi.auth2.BasicProfile |
Właściwości obiektu gapi.auth2.BasicProfile możesz pobierać, korzystając z tych metod:
|
GoogleUser.getAuthResponse(includeAuthorizationData)
Pobierz obiekt odpowiedzi z sesji uwierzytelniania użytkownika.
Argumenty | |
---|---|
includeAuthorizationData | Opcjonalnie: wartość logiczna określająca, czy token dostępu i zakresy mają być zawsze zwracane. Domyślnie token dostępu i żądane zakresy nie są zwracane, gdy fetch_basic_profile ma wartość Prawda (wartość domyślna) i nie są żądane żadne dodatkowe zakresy. |
Zwraca | |
---|---|
gapi.auth2.AuthResponse |
Obiekt gapi.auth2.AuthResponse . |
GoogleUser.reloadAuthResponse()
Wymusza odświeżenie tokena dostępu, a następnie zwraca obietnicę nowej odpowiedzi AuthResponse.
Zwraca | |
---|---|
Promise |
Promise wypełniany ponownie gapi.auth2.AuthResponse podczas ponownego wczytywania tokena OAuth.
|
gapi.auth2.AuthResponse
Odpowiedź zwrócona podczas wywoływania metod GoogleUser.getAuthResponse(includeAuthorizationData)
lub GoogleUser.reloadAuthResponse()
.
Właściwości | ||
---|---|---|
access_token |
string |
Token dostępu. |
id_token |
string |
Przyznany token identyfikatora. |
scope |
string |
Zakresy przyznane w tokenie dostępu. |
expires_in |
number |
Liczba sekund do wygaśnięcia tokena dostępu. |
first_issued_at |
number |
Sygnatura czasowa momentu, w którym użytkownik po raz pierwszy udzielił dostępu do zakresów. |
expires_at |
number |
Sygnatura czasowa wygaśnięcia tokena dostępu. |
GoogleUser.hasGrantedScopes(scopes)
Zwraca wartość „prawda”, jeśli użytkownik udzielił określonych zakresów.
Argumenty | |
---|---|
scopes | Ciąg znaków z wartościami rozdzielanymi spacjami. |
Zwraca | |
---|---|
Wartość logiczna | Prawda, jeśli zakresy zostały przyznane |
GoogleUser.grant(options)
Poproś użytkownika o dodatkowe zakresy.
Listę parametrów i kod błędu znajdziesz w sekcji GoogleAuth.signIn()
.
GoogleUser.grantOfflineAccess(options)
Uzyskaj od użytkownika uprawnienia dostępu do określonych zakresów w trybie offline.
Argumenty | |
---|---|
options |
Obiekt gapi.auth2.OfflineAccessOptions zawierający pary klucz-wartość parametrów. Przykład: { scope: 'profile email' } |
GoogleUser.disconnect()
Unieważnia wszystkie zakresy przyznane użytkownikowi przez aplikację.
Elementy interfejsu
gapi.signin2.render(id, options)
Renderuje przycisk logowania w elemencie o podanym identyfikatorze przy użyciu ustawień określonych w obiekcie options.
Argumenty | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | Identyfikator elementu, w którym ma być renderowany przycisk logowania. | ||||||||||||||||
options |
Obiekt zawierający ustawienia służące do renderowania przycisku. Na przykład: { scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }Możesz określić te opcje:
|
Zaawansowany
gapi.auth2.authorized(params, callback)
Przeprowadza jednorazową autoryzację OAuth 2.0. W zależności od używanych parametrów otworzy się wyskakujące okienko logowania Google lub spróbuje załadować żądaną odpowiedź bez powiadomienia użytkownika.
Oto przykłady zastosowania tej metody:
- Aplikacja wysyła żądanie tylko do punktu końcowego interfejsu API Google tylko raz, aby na przykład wczytać ulubione filmy użytkownika YouTube przy pierwszym logowaniu.
- Twoja aplikacja ma własną infrastrukturę do zarządzania sesją, a identyfikację użytkownika w backendzie wymaga tylko tokena identyfikatora.
- Na tej samej stronie jest używanych kilka identyfikatorów klienta.
Argumenty | |
---|---|
params |
Obiekt zawierający pary klucz-wartość danych konfiguracyjnych. W sekcji gapi.auth2.AuthorizeConfig znajdziesz różne właściwości, które można skonfigurować. Na przykład: { client_id: 'CLIENT_ID.apps.googleusercontent.com', scope: 'email profile openid', response_type: 'id_token permission' } |
callback |
Funkcja wywołana obiektem gapi.auth2.AuthorizeResponse po ukończeniu żądania (udanego lub nieudanego).
|
Przykład
gapi.auth2.authorize({
client_id: 'CLIENT_ID.apps.googleusercontent.com',
scope: 'email profile openid',
response_type: 'id_token permission'
}, function(response) {
if (response.error) {
// An error happened!
return;
}
// The user authorized the application for the scopes requested.
var accessToken = response.access_token;
var idToken = response.id_token;
// You can also now use gapi.client to perform authenticated requests.
});
Kody błędów
idpiframe_initialization_failed
- Nie udało się zainicjować wymaganego elementu iframe od Google na przykład z powodu nieobsługiwanego środowiska. Właściwość
details
zawiera więcej informacji o wykrytym błędzie. popup_closed_by_user
- Użytkownik zamknął wyskakujące okienko, zanim zakończył proces logowania.
access_denied
- Użytkownik odmówił przyznania wymaganych zakresów.
immediate_failed
- Żadnego użytkownika nie można wybrać automatycznie bez pytania użytkownika o zgodę na przetwarzanie danych osobowych. Podczas używania
signIn
z użyciem opcjiprompt: 'none'
wystąpił błąd.
gapi.auth2.AuthorizeConfig
Interfejs reprezentujący różne parametry konfiguracji metody gapi.auth2.authorize
.
Właściwości | ||
---|---|---|
client_id |
string |
Required. Identyfikator klienta aplikacji znaleziony i utworzony w Google Developers Console. |
scope |
string |
Required. Zakresy, których dotyczy żądanie, w postaci ciągu rozdzielanego spacjami. |
response_type |
string |
Lista typów odpowiedzi rozdzielanych spacjami. Domyślna wartość to 'permission' . Możliwe wartości:
|
prompt |
string |
Wymusza określony tryb procesu uzyskiwania zgody. Możliwe wartości:
|
cookie_policy |
string |
Domeny, dla których są tworzone pliki cookie używane do logowania. Może to być identyfikator URI, single_host_origin lub none . Jeśli nie określono inaczej, domyślnie jest to single_host_origin .
|
hosted_domain |
string |
Domena G Suite, do której użytkownicy muszą należeć, aby się zalogować. Ten identyfikator może być zmieniany przez klientów, dlatego pamiętaj, aby zweryfikować usługę domeny hostowanej zwróconego użytkownika. |
login_hint |
string |
Adres e-mail lub identyfikator użytkownika wstępny do wyboru podczas logowania. Użytkownik może to zmienić, chyba że używany jest prompt: "none" .
|
include_granted_scopes |
boolean |
Określa, czy żądać tokena dostępu, który obejmuje wszystkie zakresy przyznane wcześniej użytkownikowi przez aplikację, czy tylko zakresy wymagane w bieżącej rozmowie. Domyślna wartość to true .
|
plugin_name |
string |
Opcjonalnie. Jeśli ustawisz identyfikator klienta utworzony przed 29 lipca 2022 r., będzie można korzystać z Biblioteki Google Platform. Domyślnie nowo utworzone identyfikatory klientów są zablokowane i nie mogą korzystać z biblioteki platformy. Zamiast tego muszą używać nowszej biblioteki usług Google Identity. Możesz wybrać dowolną wartość. Zalecamy nazwę opisową, taką jak nazwa produktu lub wtyczki, aby ułatwić identyfikację.
Przykład: plugin_name: 'YOUR_STRING_HERE'
|
gapi.auth2.AuthorizeResponse.
Odpowiedź zwrotna dla metody gapi.auth2.authorize
.
Właściwości | ||
---|---|---|
access_token |
string |
Token dostępu. Widoczny tylko wtedy, gdy element permission lub token został określony w response_type .
|
id_token |
string |
Przyznany token identyfikatora. Jest obecny, jeśli w response_type określono id_token .
|
code |
string |
Przyznany kod autoryzacji. Jest obecny, jeśli w response_type określono code .
|
scope |
string |
Zakresy przyznane w tokenie dostępu. Widoczny tylko wtedy, gdy element permission lub token został określony w response_type .
|
expires_in |
number |
Liczba sekund do wygaśnięcia tokena dostępu. Jest obecna tylko wtedy, gdy określono permission
lub token w response_type .
|
first_issued_at |
number |
Sygnatura czasowa momentu, w którym użytkownik po raz pierwszy udzielił dostępu do zakresów. Widoczny tylko wtedy, gdy element permission lub token został określony w response_type .
|
expires_at |
number |
Sygnatura czasowa wygaśnięcia tokena dostępu. Jest obecna tylko wtedy, gdy określono permission
lub token w response_type .
|
error |
string |
Gdy żądanie się nie powiedzie, zawiera kod błędu. |
error_subtype |
string |
Gdy żądanie nie zostało zrealizowane, może zawierać dodatkowe informacje zwrócone również przez kod błędu. |