W tym artykule znajdziesz opis metod i atrybutów klienta JavaScript, które będą potrzebne do wdrożenia Logowania przez Google w Twoich aplikacjach internetowych.
Jeśli wystąpią problemy z biblioteką, zgłoś je w repozytorium GitHub.
Konfiguracja uwierzytelniania
Załaduj 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
.
Gdy inicjujesz obiekt 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 konfiguracji 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' } |
Zwroty | |
---|---|
gapi.auth2.GoogleAuth |
Obiekt gapi.auth2.GoogleAuth . Użyj metody after(), aby uzyskać obietnicę rozwiązaną po zakończeniu inicjowania obiektu gapi.auth2.GoogleAuth .
|
GoogleAuth.after(onInit, onError)
Wywołuje funkcję onInit, gdy obiekt GoogleAuth
jest w pełni zainicjowany. Jeśli podczas inicjowania wystąpi błąd (może się to zdarzyć w starych nieobsługiwanych przeglądarkach), zostanie wywołana funkcja onError.
Argumenty | |
---|---|
onInit |
Funkcja wywołana z obiektem GoogleAuth po pełnym zainicjowaniu.
|
onError |
Funkcja wywołana przez obiekt zawierający właściwość error , jeśli nie udało się uruchomić funkcji GoogleAuth .
|
Zwroty | |
---|---|
Obietnica | Promise wykonywany po zakończeniu funkcji onInit lub odrzucany, jeśli wystąpił błąd inicjowania. Zwraca go wartością zwracaną przez funkcję onInit, jeśli taka istnieje. |
Kody błędów
idpiframe_initialization_failed
- Nie udało się zainicjować wymaganego elementu iframe z Google, na przykład z powodu nieobsługiwanego środowiska. Właściwość
details
zapewni więcej informacji na temat zgłoszonego błędu.
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, w których chcesz tworzyć pliki cookie logowania. Może to być identyfikator URI, single_host_origin lub none . Jeśli nie zostanie podany, wartość domyślna to single_host_origin . |
scope |
string |
Zakresy do wysłania w postaci ciągu rozdzielanego spacjami. Opcjonalne, jeśli atrybut fetch_basic_profile nie ma wartości fałsz. |
fetch_basic_profile |
boolean |
Pobieranie podstawowych informacji z profilu użytkownika po zalogowaniu. Dodaje parametry „profile”, „email” i „openid” do żądanych zakresów. Wartość „prawda”, jeśli nie została podana. |
hosted_domain |
string |
Domena G Suite, do której użytkownicy muszą się logować. Klienci mogą to modyfikować, dlatego pamiętaj o potwierdzeniu własności domeny hostowanej przez użytkownika. Użyj klienta GoogleUser.getHostedDomain() i klienta hd w tokenie identyfikatora na serwerze, aby zweryfikować domenę.
|
ux_mode |
string |
Tryb UX używany podczas logowania się. Domyślnie otworzy się okienko z prośbą o zgodę na wykorzystanie danych. Prawidłowe wartości to popup i redirect . |
redirect_uri |
string |
Jeśli użyjesz ux_mode='redirect' , ten parametr pozwoli zastąpić domyślną właściwość redirect_uri , która będzie używana na końcu procesu uzyskiwania zgody. Domyślny redirect_uri to bieżący adres URL usunięty z parametrów zapytania i fragmentu z krzyżykiem.
|
plugin_name |
string |
Opcjonalne. Jeśli ustawisz tę wartość, nowe identyfikatory klientów utworzone przed 29 lipca 2022 r. będą mogły korzystać ze starszej biblioteki Google Platform.
Nowo utworzone identyfikatory klientów są teraz blokowane, dlatego nie mogą z niej korzystać w bibliotece Platformy tożsamości Google. Możesz użyć dowolnej wartości – zalecamy jej opisową nazwę, taką jak nazwa produktu lub wtyczki, aby ułatwić identyfikację.
Przykład: plugin_name: 'YOUR_STRING_HERE'
|
Uwierzytelnianie
GoogleAuth
to klasa jednoosobowa, która udostępnia metody umożliwiające użytkownikowi zalogowanie się za pomocą konta Google, sprawdzenie jego bieżącego stanu logowania, uzyskanie szczegółowych danych z profilu Google użytkownika, zażądanie dodatkowych zakresów i wylogowanie się z bieżące konto.
gapi.auth2.getAuthInstance()
Zwraca obiekt GoogleAuth
. Przed wywołaniem tej metody musisz zainicjować obiekt GoogleAuth
za pomocą wywołania gapi.auth2.init()
.
Zwroty | |
---|---|
gapi.auth2.GoogleAuth |
Obiekt gapi.auth2.GoogleAuth . Wykorzystaj ten obiekt do wywołania metod gapi.auth2.GoogleAuth .
|
GoogleAuth.isSignedIn.get(),
Wskazuje, czy bieżący użytkownik jest obecnie zalogowany.
Zwroty | |
---|---|
Wartość logiczna |
true , jeśli użytkownik jest zalogowany, false , gdy użytkownik jest wylogowany, lub obiekt GoogleAuth nie jest zainicjowany.
|
GoogleAuth.isSignedIn.listen(listener)
Czekaj na zmiany stanu logowania bieżącego użytkownika.
Argumenty | |
---|---|
listener |
Funkcja, która przyjmuje wartość logiczną. listen() przekazuje true do tej funkcji, gdy użytkownik się loguje, i false , gdy użytkownik się wyloguje.
|
GoogleAuth.signIn()
Loguje użytkownika z opcjami określonymi dla gapi.auth2.init()
.
Zwroty | |
---|---|
Obietnica | Promise spełniany przez instancję GoogleUser , gdy użytkownik uwierzytelni się i przyzna dostęp do żądanych zakresów, lub zostanie odrzucony z obiektem zawierającym właściwość error , jeśli wystąpił błąd (patrz poniżej. |
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:
|
Zwroty | |
---|---|
Obietnica | Promise spełniany przez instancję GoogleUser , gdy użytkownik uwierzytelni się i przyzna dostęp do żądanych zakresów, lub zostanie odrzucony z obiektem zawierającym właściwość error , jeśli wystąpił błąd (patrz poniżej. |
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 uprawnień związanych z wymaganymi zakresami.
immediate_failed
- Żaden użytkownik nie został wybrany automatycznie bez pytania o zgodę. Podczas używania właściwości
signIn
zprompt: 'none'
wystąpił błąd. Tej opcji nie należy udostępniać, ponieważgapi.auth2.init
loguje się automatycznie, jeśli użytkownik zalogował się wcześniej w 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. Opcjonalne. Możliwe wartości:
|
scope |
string |
Zakresy do wysłania w postaci ciągu rozdzielanego spacjami na podstawie zakresów zdefiniowanych w parametrach gapi.auth2.init . Opcjonalne, jeśli atrybut fetch_basic_profile nie ma wartości Fałsz.
|
ux_mode |
string |
Tryb UX używany podczas logowania się. Domyślnie otworzy się okienko z prośbą o zgodę na wykorzystanie danych. Prawidłowe wartości to popup i redirect . |
redirect_uri |
string |
Jeśli użyjesz ux_mode='redirect' , ten parametr pozwoli zastąpić domyślną właściwość redirect_uri , która będzie używana na końcu procesu uzyskiwania zgody. Domyślny redirect_uri to bieżący adres URL usunięty z parametrów zapytania i fragmentu z krzyżykiem.
|
GoogleAuth.signOut()
Wylogowuje z konta bieżące konto.
Zwroty | |
---|---|
Obietnica | Wartość Promise wypełniana po wylogowaniu użytkownika. |
GoogleAuth.disconnect()
Unieważnia wszystkie zakresy przyznane przez użytkownika.
GoogleAuth.grantOfflineAccess(options)
Poproś użytkownika o dostęp do określonych zakresów offline.
Argumenty | |
---|---|
options |
Obiekt gapi.auth2.OfflineAccessOptions zawierający pary klucz-wartość parametrów. Przykład: { scope: 'profile email' } |
Zwroty | |
---|---|
Obietnica | Wystąpienie Promise realizowane, gdy użytkownik przyznaje wymagane 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 zakończył proces uzyskiwania zgody.
access_denied
- Użytkownik odmówił przyznania uprawnień związanych z wymaganymi zakresami.
immediate_failed
- Żaden użytkownik nie został wybrany automatycznie bez pytania o zgodę. Podczas używania właściwości
signIn
zprompt: 'none'
wystąpił błąd. Tej opcji nie należy udostępniać, ponieważgapi.auth2.init
loguje się automatycznie, jeśli użytkownik zalogował się wcześniej w poprzedniej sesji.
gapi.auth2.OfflineAccessOptions
Interfejs reprezentujący różne parametry konfiguracji metody GoogleAuth.grantOfflineAccess(options)
.
Parametry | ||
---|---|---|
prompt |
string |
Wymusza określony tryb procesu uzyskiwania zgody. Opcjonalne. Możliwe wartości:
|
scope |
string |
Zakresy do wysłania w postaci ciągu rozdzielanego spacjami na podstawie zakresów zdefiniowanych w parametrach gapi.auth2.init . Opcjonalne, jeśli atrybut fetch_basic_profile nie ma wartości Fałsz.
|
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
Dołącza proces logowania do modułu obsługi kliknięcia określonego kontenera.
Argumenty | |
---|---|
container | Identyfikator lub odniesienie dodiv element, 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 być wywoływana po zakończeniu logowania. |
onfailure | Funkcja wywołania, jeśli nie uda się zalogować. |
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
, który reprezentuje bieżącego użytkownika. W przypadku nowo zainicjowanej instancji GoogleAuth
bieżący użytkownik nie został ustawiony. Aby uzyskać zainicjowane wystąpienie GoogleAuth
, użyj metody currentUser.listen()
lub GoogleAuth.then()
.
Zwroty | |
---|---|
GoogleUser |
Bieżący użytkownik |
GoogleAuth.currentUser.listen(listener)
Monitoruj zmiany dotyczące bieżącego użytkownika.
Argumenty | |
---|---|
listener |
Funkcja, która przyjmuje parametr GoogleUser .
listen przekazuje tę funkcję do instancji GoogleUser przy każdej zmianie, która zmienia currentUser .
|
GoogleUser.getId(),
Pobierz unikalny ciąg identyfikatora użytkownika.
Zwroty | |
---|---|
Ciąg znaków | unikalny identyfikator użytkownika, |
GoogleUser.isSignedIn().
Zwraca wartość „prawda”, jeśli użytkownik jest zalogowany.
Zwroty | |
---|---|
Wartość logiczna | Prawda, jeśli użytkownik jest zalogowany |
GoogleUser.getHostedDomain().
Pobierz domenę G Suite użytkownika, jeśli zalogował się na konto G Suite.
Zwroty | |
---|---|
Ciąg znaków | Domena G Suite użytkownika |
GoogleUser.getGrantedScopes(),
Pobierz zakresy nadane przez użytkownika w postaci ciągu rozdzielanego spacjami.
Zwroty | |
---|---|
Ciąg znaków | Zakresy przyznane przez użytkownika |
GoogleUser.getBasicProfile().
Uzyskaj podstawowe informacje o użytkowniku w profilu.
Zwroty | |
---|---|
gapi.auth2.BasicProfile |
Właściwości gapi.auth2.BasicProfile możesz pobrać za pomocą tych metod:
|
GoogleUser.getAuthResponse(includeAuthorizationData)
Pobierz obiekt odpowiedzi z sesji uwierzytelniania użytkownika.
Argumenty | |
---|---|
includeAuthorizationData | Opcjonalnie: wartość logiczna, która określa, czy zawsze ma być zwracany token dostępu i zakresy. Domyślnie token dostępu i żądane zakresy nie są zwracane, gdy fetch_basic_profile ma wartość domyślną (wartość domyślna) i nie są żądane żadne dodatkowe zakresy. |
Zwroty | |
---|---|
gapi.auth2.AuthResponse |
Obiekt gapi.auth2.AuthResponse . |
GoogleUser.reloadAuthResponse()
Wymusza odświeżenie tokena dostępu, a następnie zwraca obietnicę nowej AuthResponse.
Zwroty | |
---|---|
Promise |
Promise wypełniany po załadowaniu gapi.auth2.AuthResponse podczas ponownego wczytywania tokena OAuth.
|
gapi.auth2.AuthResponse
Odpowiedź zwrócona przy wywołaniu metod GoogleUser.getAuthResponse(includeAuthorizationData)
lub GoogleUser.reloadAuthResponse()
.
Właściwości | ||
---|---|---|
access_token |
string |
Token dostępu został przyznany. |
id_token |
string |
Przyznano 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, w której użytkownik przyznał najpierw wymagane zakresy. |
expires_at |
number |
Sygnatura czasowa, w której token dostępu wygaśnie. |
GoogleUser.hasGrantedScopes(scopes)
Zwraca wartość „prawda”, jeśli użytkownik przyznał określone zakresy.
Argumenty | |
---|---|
scopes | Ciąg rozdzielany spacjami. |
Zwroty | |
---|---|
Wartość logiczna | Prawda, jeśli zakresy zostały przyznane |
GoogleUser.grant(options)
Poproś użytkownika o dodatkowe zakresy.
Na stronie GoogleAuth.signIn()
znajdziesz listę parametrów i kod błędu.
GoogleUser.grantOfflineAccess(options)
Poproś użytkownika o dostęp do określonych zakresów 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 z użyciem ustawień określonych przez obiekt options.
Argumenty | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | Identyfikator elementu, w którym jest 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:
|
Zaawansowane
gapi.auth2.authorize(params, callback)
Przeprowadza jednorazową autoryzację OAuth 2.0. W zależności od używanych parametrów otworzy się wyskakujące okienko procesu logowania Google lub spróbujemy wczytać żądaną odpowiedź bez powiadomienia użytkownika.
Przykłady użycia, gdy ta metoda jest przydatna:
- Aplikacja wysyła żądanie tylko do punktu końcowego interfejsu API Google tylko raz, na przykład aby wczytać ulubione filmy użytkownika przy pierwszym logowaniu.
- Twoja aplikacja ma własną infrastrukturę do zarządzania sesją. Token ten wymaga tylko raz, aby zidentyfikować użytkownika w backendzie.
- Na tej samej stronie znajduje się 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ływana z obiektem gapi.auth2.AuthorizeResponse po zakończeniu żądania (powodzenie lub błąd).
|
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 z Google, na przykład z powodu nieobsługiwanego środowiska. Właściwość
details
zapewni więcej informacji na temat zgłoszonego błędu. popup_closed_by_user
- Użytkownik zamknął wyskakujące okienko, zanim zakończył proces logowania.
access_denied
- Użytkownik odmówił przyznania uprawnień związanych z wymaganymi zakresami.
immediate_failed
- Żaden użytkownik nie został wybrany automatycznie bez pytania o zgodę. Podczas używania właściwości
signIn
zprompt: '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 do wysłania w postaci ciągu rozdzielanego spacjami. |
response_type |
string |
Lista typów odpowiedzi rozdzielonych 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, w których chcesz tworzyć pliki cookie logowania. Może to być identyfikator URI, single_host_origin lub none . Jeśli nie zostanie podany, wartość domyślna to single_host_origin .
|
hosted_domain |
string |
Domena G Suite, do której użytkownicy muszą się logować. Jest to narażone na modyfikowanie przez klientów, więc pamiętaj, aby zweryfikować właściwość domeny hostowanego użytkownika. |
login_hint |
string |
Adres e-mail lub identyfikator użytkownika do wstępnego 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 zawierającego wszystkie zakresy przyznane wcześniej użytkownikowi przez aplikację, czy tylko zakresy żądane w bieżącym wywołaniu. Domyślna wartość to true .
|
plugin_name |
string |
Opcjonalne. Jeśli ustawisz identyfikator klienta utworzony przed 29 lipca 2022 roku, będzie on mógł korzystać z Biblioteki Google Platform. Nowo utworzone identyfikatory klientów są domyślnie zablokowane i muszą być w niej używane z biblioteką usług tożsamości Google. Możesz użyć dowolnej wartości – w celu łatwej identyfikacji zalecamy podanie nazwy opisowej, takiej jak nazwa produktu lub wtyczki.
Przykład: plugin_name: 'YOUR_STRING_HERE'
|
gapi.auth2.AuthorizeResponse
Odpowiedź na wywołanie zwrotne metody gapi.auth2.authorize
.
Właściwości | ||
---|---|---|
access_token |
string |
Token dostępu został przyznany. Jest obecny tylko wtedy, gdy właściwość permission lub token została określona w polu response_type .
|
id_token |
string |
Przyznano token identyfikatora. Występuje tylko wtedy, gdy element id_token został określony w response_type .
|
code |
string |
Kod autoryzacji został przyznany. Występuje tylko wtedy, gdy element code został określony w response_type .
|
scope |
string |
Zakresy przyznane w tokenie dostępu. Widoczne tylko wtedy, gdypermission lubtoken został określony wresponse_type ,
|
expires_in |
number |
Liczba sekund do wygaśnięcia tokena dostępu. Widoczne tylko wtedy, gdypermission lubtoken został określony wresponse_type ,
|
first_issued_at |
number |
Sygnatura czasowa, w której użytkownik przyznał najpierw wymagane zakresy. Widoczne tylko wtedy, gdy
permission lubtoken został określony wresponse_type ,
|
expires_at |
number |
Sygnatura czasowa, w której token dostępu wygaśnie. Widoczne tylko wtedy, gdypermission lubtoken został określony wresponse_type ,
|
error |
string |
Gdy żądanie się nie powiedzie, zawiera kod błędu. |
error_subtype |
string |
Jeśli żądanie nie zostało zrealizowane, może zawierać dodatkowe informacje o kodzie błędu. |