Bu referansta, Google ile Oturum Açma özelliğini web uygulamalarınıza uygulamak için kullanacağınız JavaScript istemci yöntemleri ve özellikleri açıklanmaktadır.
Kitaplığı kullanırken herhangi bir sorunla karşılaşırsanız lütfen GitHub depomuza bildirin.
Auth Kurulumu
gapi
nesnesini oluşturmak için Google API'leri platform kitaplığını yükleyin:
<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>
Platform kitaplığı yüklendikten sonra auth2
kitaplığını yükleyin:
function init() {
gapi.load('auth2', function() {
/* Ready. Make a call to gapi.auth2.init or some other API */
});
}
gapi.auth2.init(params)
GoogleAuth
nesnesini başlatır. gapi.auth2.GoogleAuth
yöntemlerini çağırmadan önce bu yöntemi çağırmanız gerekir.
GoogleAuth
nesnesini başlattığınızda nesneyi OAuth 2.0 istemci kimliğinizle ve belirtmek istediğiniz ek seçeneklerle yapılandırırsınız. Ardından, kullanıcı zaten oturum açtıysa GoogleAuth
nesnesi, kullanıcının önceki oturumdaki oturum açma durumunu geri yükler.
Bağımsız değişkenler | |
---|---|
params |
İstemci yapılandırma verilerinin anahtar/değer çiftlerini içeren bir nesne. Yapılandırılabilir farklı özellikler için gapi.auth2.ClientConfig belgesine bakın. Örneğin:
{ client_id: 'CLIENT_ID.apps.googleusercontent.com' } |
İadeler | |
---|---|
gapi.auth2.GoogleAuth |
gapi.auth2.GoogleAuth nesnesi. gapi.auth2.GoogleAuth nesnesinin başlatılması tamamlandığında çözümlenen bir Promise almak için then() yöntemini kullanın.
|
GoogleAuth.then(onInit, onError)
GoogleAuth
nesnesi tamamen başlatıldığında onInit işlevini çağırır. Başlatma sırasında bir hata oluşursa (bu durum, desteklenmeyen eski tarayıcılarda meydana gelebilir) yerine onError işlevi çağrılır.
Bağımsız değişkenler | |
---|---|
onInit |
Tamamen başlatıldığında GoogleAuth nesnesiyle çağrılan işlev.
|
onError |
GoogleAuth başlatılamadıysa error özelliğini içeren bir nesneyle çağrılan işlev.
|
İadeler | |
---|---|
Söz ver | onInit işlevi tamamlandığında sağlanan veya başlatma hatası oluştuğunda reddedilen bir Promise . Varsa onInit işlevinden döndürülen değerle çözümlenir. |
Hata Kodları
idpiframe_initialization_failed
-
Örneğin, desteklenmeyen bir ortam nedeniyle Google'dan gerekli bir iframe başlatılamadı.
details
özelliği, ortaya çıkan hatayla ilgili daha fazla bilgi verir.
gapi.auth2.ClientConfig
gapi.auth2.init
yöntemi için farklı yapılandırma parametrelerini temsil eden arayüz.
Parametreler | ||
---|---|---|
client_id |
string |
Zorunludur. Google Developers Console'da bulunan ve oluşturulan uygulamanın istemci kimliği. |
cookie_policy |
string |
Oturum açma çerezlerinin oluşturulacağı alanlar. URI, single_host_origin veya none . Belirtilmemişse varsayılan olarak single_host_origin değerine ayarlanır. |
scope |
string |
Boşlukla sınırlandırılmış bir dize olarak, istenecek kapsamlar. fetch_basic_profile yanlış değerine ayarlanmamışsa isteğe bağlıdır. |
fetch_basic_profile |
boolean |
Oturum açtıklarında kullanıcıların temel profil bilgilerini alın. İstenen kapsamlara "profile", "email" ve "openid" ekler. Belirtilmemişse doğru değerini alır. |
hosted_domain |
string |
Kullanıcıların oturum açabilmek için ait olması gereken G Suite alanı. Bu durum, istemciler tarafından değiştirilebilir. Bu nedenle, döndürülen kullanıcının barındırılan alan özelliğini doğruladığınızdan emin olun. İstemcide GoogleUser.get hostedDomain() kullanın ve alanın beklediğiniz gibi olduğunu doğrulamak için sunucudaki Kimlik Jetonu'ndaki hd hak talebini kullanın.
|
ux_mode |
string |
Oturum açma akışı için kullanılacak kullanıcı deneyimi modu. Varsayılan olarak izin akışını bir pop-up'ta açar. Geçerli değerler popup ve redirect 'dir. |
redirect_uri |
string |
ux_mode='redirect' kullanılıyorsa bu parametre, izin akışının sonunda kullanılacak varsayılan redirect_uri değerini geçersiz kılmanıza olanak tanır. Varsayılan redirect_uri , sorgu parametreleri ve karma parçasından arındırılmış geçerli URL'dir.
|
plugin_name |
string |
İsteğe bağlı. Bu değer ayarlanırsa 29 Temmuz 2022'den önce oluşturulan yeni istemci kimlikleri, eski Google Platform Kitaplığı'nı kullanabilir.
Varsayılan olarak, yeni oluşturulan İstemci Kimliklerinin artık Platform Kitaplığı'nı kullanması engellenmiştir ve bunun yerine yeni Google Kimlik Hizmetleri kitaplığını kullanması gerekir. Herhangi bir değer seçebilirsiniz. Kolay tanımlama için ürün veya eklenti adı gibi açıklayıcı bir ad önerilir.
Örnek: plugin_name: 'YOUR_STRING_HERE'
|
Kimlik doğrulama
GoogleAuth
, kullanıcının bir Google Hesabı ile oturum açmasına, kullanıcının mevcut oturum açma durumunu öğrenmesine, kullanıcının Google profilinden belirli verileri almasına, ek kapsam istemesine ve geçerli hesaptan çıkış yapmasına olanak tanıyan yöntemler sunan bir tekil sınıftır.
gapi.auth2.getAuthInstance()
GoogleAuth
nesnesini döndürür. Bu yöntemi çağırmadan önce GoogleAuth
nesnesini gapi.auth2.init()
ile başlatmanız gerekir.
İadeler | |
---|---|
gapi.auth2.GoogleAuth |
gapi.auth2.GoogleAuth nesnesi. gapi.auth2.GoogleAuth yöntemlerini çağırmak için bu nesneyi kullanın.
|
GoogleAuth.isSignIn.get()
Geçerli kullanıcının oturum açmış olup olmadığını döndürür.
İadeler | |
---|---|
Boole |
Kullanıcı oturum açtıysa true veya kullanıcı oturumu kapalıysa ya da GoogleAuth nesnesi başlatılmadıysa false .
|
GoogleAuth.isSignIn.listen(dinleyici)
Mevcut kullanıcının oturum açma durumundaki değişiklikleri dinleyin.
Bağımsız değişkenler | |
---|---|
listener |
Boole değeri alan işlev. listen() , kullanıcı oturum açtığında true ve oturumu kapattığında false öğesini bu işleve geçirir.
|
GoogleAuth.signIn()
gapi.auth2.init()
için belirtilen seçeneklerle kullanıcının oturumunu açar.
İadeler | |
---|---|
Söz ver | Kullanıcı, kimlik doğrulamasını başarılı bir şekilde yapıp istenen kapsamları verdiğinde veya hata meydana gelirse error özelliğini içeren bir nesneyle reddedildiğinde GoogleUser örneğiyle tamamlanan bir Promise (hata kodları için aşağıya bakın). |
Hata kodları
Şu sayfaya göz atın: GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Belirtilen seçenekleri kullanarak kullanıcının oturumunu açar.
Bağımsız değişkenler | |
---|---|
options |
Aşağıdakiler koşullardan en az biri karşılanmalıdır:
|
İadeler | |
---|---|
Söz ver | Kullanıcı, kimlik doğrulamasını başarılı bir şekilde yapıp istenen kapsamları verdiğinde veya hata meydana gelirse error özelliğini içeren bir nesneyle reddedildiğinde GoogleUser örneğiyle tamamlanan bir Promise (hata kodları için aşağıya bakın). |
Hata kodları
popup_closed_by_user
- Kullanıcı, oturum açma akışını tamamlamadan pop-up'ı kapattı.
access_denied
- Kullanıcı, gerekli kapsamlara yönelik izni reddetti.
immediate_failed
-
İzin akışı istenmeden hiçbir kullanıcı otomatik olarak seçilemedi.
prompt: 'none'
seçeneği ilesignIn
kullanılırken hata oluştu. Önceki bir oturumda daha önce oturum açıldıysagapi.auth2.init
kullanıcının oturumunu otomatik olarak açacağından bu seçeneğin kullanılması zorunlu değildir.
gapi.auth2.SignInOptions
GoogleAuth.signIn(options)
yöntemi için farklı yapılandırma parametrelerini temsil eden arayüz.
Parametreler | ||
---|---|---|
prompt |
string |
İzin akışı için belirli bir modu zorlar. İsteğe bağlı. Olası değerler şunlardır:
|
scope |
string |
gapi.auth2.init parametrelerinde tanımlanan kapsamların üzerinde, boşlukla sınırlandırılmış bir dize olarak istenecek kapsamlar. fetch_basic_profile yanlış değerine ayarlanmadıysa isteğe bağlıdır.
|
ux_mode |
string |
Oturum açma akışı için kullanılacak kullanıcı deneyimi modu. Varsayılan olarak izin akışını bir pop-up'ta açar. Geçerli değerler popup ve redirect 'dir. |
redirect_uri |
string |
ux_mode='redirect' kullanılıyorsa bu parametre, izin akışının sonunda kullanılacak varsayılan redirect_uri değerini geçersiz kılmanıza olanak tanır. Varsayılan redirect_uri , sorgu parametreleri ve karma parçasından arınmış geçerli URL'dir.
|
GoogleAuth.signOut()
Uygulamadaki mevcut hesabın oturumunu kapatır.
İadeler | |
---|---|
Söz ver | Kullanıcı oturumu kapatıldığında sağlanan bir Promise . |
GoogleAuth.disconnect()
Kullanıcının verdiği tüm kapsamları iptal eder.
GoogleAuth.grantofflineAccess(options)
Belirtilen kapsamlara çevrimdışı olarak erişmek için kullanıcıdan izin alın.
Bağımsız değişkenler | |
---|---|
options |
Parametre anahtar/değer çiftlerini içeren bir gapi.auth2.OfflineAccessOptions nesnesi. Örneğin: { scope: 'profile email' } |
İadeler | |
---|---|
Söz ver | Kullanıcı, istenen kapsamları verdiğinde ve yetkilendirme kodunu içeren bir nesneyi Promise 'in istek karşılama işleyicisine ilettiğinde yerine getirilen Promise .
Örneğin: auth2.grantOfflineAccess().then(function(resp) { var auth_code = resp.code; }); |
Hata kodları
popup_closed_by_user
- Kullanıcı, izin akışını tamamlamadan pop-up'ı kapattı.
access_denied
- Kullanıcı, gerekli kapsamlara yönelik izni reddetti.
immediate_failed
-
İzin akışı istenmeden hiçbir kullanıcı otomatik olarak seçilemedi.
prompt: 'none'
seçeneği ilesignIn
kullanılırken hata oluştu. Önceki bir oturumda daha önce oturum açıldıysagapi.auth2.init
kullanıcının oturumunu otomatik olarak açacağından bu seçeneğin kullanılması zorunlu değildir.
gapi.auth2.offlineAccessOptions
GoogleAuth.grantOfflineAccess(options)
yöntemi için farklı yapılandırma parametrelerini temsil eden arayüz.
Parametreler | ||
---|---|---|
prompt |
string |
İzin akışı için belirli bir modu zorlar. İsteğe bağlı. Olası değerler şunlardır:
|
scope |
string |
gapi.auth2.init parametrelerinde tanımlanan kapsamların üzerinde, boşlukla sınırlandırılmış bir dize olarak istenecek kapsamlar. fetch_basic_profile yanlış değerine ayarlanmadıysa isteğe bağlıdır.
|
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
Oturum açma akışını, belirtilen kapsayıcının tıklama işleyicisine ekler.
Bağımsız değişkenler | |
---|---|
container | Tıklama işleyicinin ekleneceği div öğesinin kimliği veya referansı. |
options | Parametrelerden oluşan anahtar/değer çiftlerini içeren bir nesne. GoogleAuth.signIn() konusuna bakın. |
onsuccess | Oturum açma işlemi tamamlandıktan sonra çağrılacak işlev. |
onfailure | Oturum açma başarısız olursa çağrılacak işlev. |
Kullanıcılar
GoogleUser
nesnesi bir kullanıcı hesabını temsil eder.
GoogleUser
nesneleri genellikle GoogleAuth.currentUser.get() çağrısıyla elde edilir.
GoogleAuth.currentUser.get()
Geçerli kullanıcıyı temsil eden bir GoogleUser
nesnesi döndürür. Yeni başlatılan bir GoogleAuth
örneğinde geçerli kullanıcının ayarlanmadığını unutmayın. Başlatılmış bir GoogleAuth
örneği almak için currentUser.listen()
yöntemini veya GoogleAuth.then()
yöntemini kullanın.
İadeler | |
---|---|
GoogleUser |
Geçerli kullanıcı |
GoogleAuth.currentUser.listen(listener)
currentUser'daki değişiklikleri dinleyin.
Bağımsız değişkenler | |
---|---|
listener |
GoogleUser parametresini alan işlev.
listen , currentUser üzerinde değişiklik yapan her değişiklikte bu işleve bir GoogleUser örneği iletir.
|
GoogleKullanıcısı.getId()
Kullanıcının benzersiz kimlik dizesini alın.
İadeler | |
---|---|
Dize | Kullanıcının benzersiz kimliği |
GoogleKullanıcısı.issignIn()
Kullanıcı oturum açtıysa true değerini döndürür.
İadeler | |
---|---|
Boole | Kullanıcı oturum açtıysa doğru değerini alır |
GoogleUser.getBarındırılanAlan()
Kullanıcı bir G Suite hesabıyla oturum açtıysa kullanıcının G Suite alanını alın.
İadeler | |
---|---|
Dize | Kullanıcının G Suite alanı |
GoogleUser.getGrantedScopes()
Kullanıcının izin verdiği kapsamları boşlukla ayrılmış bir dize olarak alın.
İadeler | |
---|---|
Dize | Kullanıcının verdiği kapsamlar |
GoogleUser.getBasicProfile()
Kullanıcının temel profil bilgilerini alın.
İadeler | |
---|---|
gapi.auth2.BasicProfile |
gapi.auth2.BasicProfile özelliklerini aşağıdaki yöntemlerle alabilirsiniz:
|
GoogleUser.getAuthResponse(includeAuthorizationData)
Kullanıcının kimlik doğrulama oturumundan yanıt nesnesini alın.
Bağımsız değişkenler | |
---|---|
includeAuthorizationData | İsteğe bağlı: Erişim jetonu ve kapsamların her zaman döndürülüp döndürülmeyeceğini belirten boole. fetch_basic_profile doğru (varsayılan değer) olduğunda ve ek kapsam istenmediğinde erişim jetonu ve istenen kapsamlar varsayılan olarak döndürülmez. |
İadeler | |
---|---|
gapi.auth2.AuthResponse |
gapi.auth2.AuthResponse nesnesi. |
GoogleUser.reloadAuthResponse()
Erişim jetonunun yenilenmesini zorunlu kılar ve ardından yeni AuthResponse için bir Promise döndürür.
İadeler | |
---|---|
Promise |
OAuth jetonunun yeniden yüklenmesi tamamlandığında yeniden yüklenen gapi.auth2.AuthResponse ile tamamlanan bir Promise .
|
gapi.auth2.AuthResponse
GoogleUser.getAuthResponse(includeAuthorizationData)
veya GoogleUser.reloadAuthResponse()
yöntemleri çağrılırken yanıt döndürüldü.
Özellikler | ||
---|---|---|
access_token |
string |
Erişim Jetonu verildi. |
id_token |
string |
Verilen kimlik jetonu. |
scope |
string |
Erişim Jetonu'nda verilen kapsamlar. |
expires_in |
number |
Erişim jetonunun sona ermesine kadar geçen saniye sayısıdır. |
first_issued_at |
number |
Kullanıcının istenen kapsamları ilk kez verdiği zaman damgası. |
expires_at |
number |
Erişim Jetonu'nun süresinin dolacağı zaman damgası. |
GoogleUser.hasGrantedScopes(scopes)
Kullanıcı belirtilen kapsamları verdiyse true değerini döndürür.
Bağımsız değişkenler | |
---|---|
scopes | Boşlukla sınırlandırılmış bir kapsam dizesi. |
İadeler | |
---|---|
Boole | Kapsamlar verilmişse doğru değerini alır |
GoogleKullanıcı.grant(options)
Kullanıcıya ek kapsamlar isteyin.
Parametre listesi ve hata kodu için GoogleAuth.signIn()
adresine bakın.
GoogleUser.grantÇevrimdışıAccess(options)
Belirtilen kapsamlara çevrimdışı olarak erişmek için kullanıcıdan izin alın.
Bağımsız değişkenler | |
---|---|
options |
Parametre anahtar/değer çiftlerini içeren bir gapi.auth2.OfflineAccessOptions nesnesi. Örneğin: { scope: 'profile email' } |
GoogleKullanıcısı.disconnect()
Kullanıcının uygulama için verdiği tüm kapsamları iptal eder.
Kullanıcı arayüzü öğeleri
gapi.signin2.render(id, options)
options nesnesi tarafından belirtilen ayarları kullanarak, belirtilen kimliğe sahip öğede bir oturum açma düğmesi oluşturur.
Bağımsız değişkenler | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | Oturum açma düğmesinin oluşturulacağı öğenin kimliği. | ||||||||||||||||
options |
Düğmeyi oluşturmak için kullanılacak ayarları içeren bir nesne. Örneğin:
{ scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }Aşağıdaki seçenekleri belirtebilirsiniz:
|
Gelişmiş
gapi.auth2.authorized(params, callback)
Bir defalık OAuth 2.0 yetkilendirmesi gerçekleştirir. Kullanılan parametrelere bağlı olarak, bu işlem Google ile oturum açma akışında bir pop-up açar veya istenen yanıtı kullanıcı etkileşimi olmadan sessiz bir şekilde yüklemeye çalışır.
Bu yöntemin yararlı olduğu bazı kullanım alanları şunlardır:
- Uygulamanızın yalnızca bir Google API uç noktası istemesi yeterlidir. Örneğin, kullanıcının favori YouTube videolarını kullanıcı ilk kez oturum açtığında yüklemek için bu uç nokta doğrulanır.
- Uygulamanızın kendi oturum yönetimi altyapısı vardır ve arka ucunuzda kullanıcıyı tanımlamak için Kimlik Jetonu'nu yalnızca bir kez gerektirir.
- Aynı sayfada birkaç İstemci Kimliği kullanılır.
Bağımsız değişkenler | |
---|---|
params |
Yapılandırma verilerinin anahtar/değer çiftlerini içeren bir nesne. Yapılandırılabilir farklı özellikler için gapi.auth2.AuthorizeConfig sayfasına bakın. Örneğin:
{ client_id: 'CLIENT_ID.apps.googleusercontent.com', scope: 'email profile openid', response_type: 'id_token permission' } |
callback |
İstek tamamlandıktan sonra (başarıyla veya bir hatayla) gapi.auth2.AuthorizeResponse nesnesiyle çağrılan işlev.
|
Örnek
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.
});
Hata kodları
idpiframe_initialization_failed
-
Örneğin, desteklenmeyen bir ortam nedeniyle Google'dan gerekli bir iframe başlatılamadı.
details
özelliği, ortaya çıkan hatayla ilgili daha fazla bilgi verir. popup_closed_by_user
- Kullanıcı, oturum açma akışını tamamlamadan pop-up'ı kapattı.
access_denied
- Kullanıcı, gerekli kapsamlara yönelik izni reddetti.
immediate_failed
-
İzin akışı istenmeden hiçbir kullanıcı otomatik olarak seçilemedi.
prompt: 'none'
seçeneği ilesignIn
kullanılırken hata oluştu.
gapi.auth2.AuthorizeConfig
gapi.auth2.authorize
yöntemi için farklı yapılandırma parametrelerini temsil eden arayüz.
Özellikler | ||
---|---|---|
client_id |
string |
Zorunludur. Google Developers Console'da bulunan ve oluşturulan uygulamanın istemci kimliği. |
scope |
string |
Zorunludur. Boşlukla sınırlandırılmış bir dize olarak, istenecek kapsamlar. |
response_type |
string |
Boşlukla sınırlandırılmış bir yanıt türü listesi. Varsayılan olarak 'permission' değerine ayarlanır. Olası değerler şunlardır:
|
prompt |
string |
İzin akışı için belirli bir modu zorlar. Olası değerler şunlardır:
|
cookie_policy |
string |
Oturum açma çerezlerinin oluşturulacağı alanlar. URI, single_host_origin veya none . Belirtilmemişse varsayılan olarak single_host_origin değerine ayarlanır.
|
hosted_domain |
string |
Kullanıcıların oturum açabilmek için ait olması gereken G Suite alanı. Bu durum, istemciler tarafından değiştirilebilir. Bu nedenle, döndürülen kullanıcının barındırılan alan özelliğini doğruladığınızdan emin olun. |
login_hint |
string |
Oturum açma akışında önceden seçilecek bir kullanıcının e-posta adresi veya User-ID. prompt: "none" kullanılmadığı sürece bu durum kullanıcı tarafından değiştirilebilir.
|
include_granted_scopes |
boolean |
Kullanıcı tarafından daha önce uygulamaya verilen tüm kapsamları veya yalnızca geçerli çağrıda istenen kapsamları içeren bir Erişim Jetonu istenip istenmeyeceğini belirtir. Varsayılan olarak true değerine ayarlanır.
|
plugin_name |
string |
İsteğe bağlı. Ayarlanırsa 29 Temmuz 2022'den önce oluşturulan istemci kimlikleri, Google Platform Kitaplığı'nı kullanabilir. Varsayılan olarak, yeni oluşturulan İstemci Kimliklerinin Platform Kitaplığı'nı kullanması engellenir ve bunun yerine yeni Google Kimlik Hizmetleri kitaplığını kullanması gerekir. Herhangi bir değer seçebilirsiniz. Kolay tanımlama için ürün veya eklenti adı gibi açıklayıcı bir ad önerilir.
Örnek: plugin_name: 'YOUR_STRING_HERE'
|
gapi.auth2.AuthorizeResponse
Yanıt, gapi.auth2.authorize
yönteminin geri çağırmasına döndürüldü.
Özellikler | ||
---|---|---|
access_token |
string |
Erişim Jetonu verildi. Yalnızca response_type içinde permission veya token belirtilmişse mevcut olur.
|
id_token |
string |
Verilen kimlik jetonu. Yalnızca response_type içinde id_token belirtilmişse mevcut olur.
|
code |
string |
Yetkilendirme Kodu verildi. Yalnızca response_type içinde code belirtilmişse mevcut olur.
|
scope |
string |
Erişim Jetonu'nda verilen kapsamlar. Yalnızca response_type içinde permission veya token belirtilmişse mevcut olur.
|
expires_in |
number |
Erişim jetonunun sona ermesine kadar geçen saniye sayısıdır. Yalnızca response_type içinde permission veya token belirtilmişse mevcut olur.
|
first_issued_at |
number |
Kullanıcının istenen kapsamları ilk kez verdiği zaman damgası. Yalnızca response_type içinde permission veya token belirtilmişse mevcut olur.
|
expires_at |
number |
Erişim Jetonu'nun süresinin dolacağı zaman damgası. Yalnızca response_type içinde permission veya token belirtilmişse mevcut olur.
|
error |
string |
İstek başarısız olduğunda bu mesaj, hata kodunu içerir. |
error_subtype |
string |
İstek başarısız olduğunda bu özette, döndürülen hata koduyla ilgili ek bilgiler de bulunabilir. |