Genel bakış

Entegrasyon yolunuzu seçin

İhtiyaçlarınıza en uygun yolu seçin:

Yol	En uygun olduğu durumlar	Daha fazla bilgi
Evrensel Ticaret Protokolü (UCP)	Satıcılar ve perakendeciler.	UCP Docs
Standart Hesap Bağlama	Akıllı Ev, TV ve YouTube	Dokümanlar

Not: Bu entegrasyon yolları birbirini tamamlayıcı niteliktedir. UCP'yi uyguluyorsanız ürüne özel şartlar için UCP Kimlik Bağlantısı kılavuzunu ve temel OAuth uygulama ayrıntıları için bu dokümanı incelemenizi öneririz.

Hesap bağlama, Google Hesabı sahiplerinin hizmetlerinize hızlı, sorunsuz ve güvenli bir şekilde bağlanmasını sağlar. Kullanıcı verilerini platformunuzdan Google uygulamaları ve hizmetleriyle paylaşmak için Google Hesabı bağlantısı'nı uygulamayı seçebilirsiniz.

Güvenli OAuth 2.0 protokolü, kullanıcının Google Hesabı'nı platformunuzdaki hesabıyla güvenli bir şekilde bağlamanıza olanak tanır. Böylece Google uygulamaları ve cihazları hizmetlerinize erişebilir.

Kullanıcılar, Google Hesabı bağlantısı özelliğiyle hesaplarını bağlayabilir veya bağlantılarını kaldırabilir ve isteğe bağlı olarak platformunuzda yeni bir hesap oluşturabilir.

Kullanım alanları

Google Hesabı bağlantısını uygulamanın bazı nedenleri şunlardır:

• Platformunuzdaki kullanıcı verilerini Google uygulamaları ve hizmetleriyle paylaşma

• Evrensel Ticaret Protokolü (UCP)'nü kullanarak Google Alışveriş ve yapay zeka platformlarıyla (Arama, Gemini) entegrasyon yapın.

• Video ve film içeriklerinizi Google TV'yi kullanarak oynatın.

• Google Home uygulamasını ve Google Asistan'ı kullanarak Google Akıllı Ev'e bağlı cihazları yönetip kontrol edin. Örneğin, "Hey Google, ışıkları aç" diyebilirsiniz.

• Sohbet Etme İşlemleri ile kullanıcı tarafından özelleştirilmiş Google Asistan deneyimleri ve işlevleri oluşturun. "Ok Google, Starbucks'tan her zamanki siparişimi ver."

• Kullanıcıların Google Hesaplarını bir ödül iş ortağı hesabına bağladıktan sonra YouTube'da uygun canlı yayınları izleyerek ödül kazanmalarını sağlayın.

• Kayıt sırasında yeni hesapları, Google Hesabı profilinden izin alınarak paylaşılan verilerle önceden doldurma.

Özellikler ve şartlar

Aşağıdaki matris, her bağlantı akışı için destek ve önerileri tanımlar.

Bağlantı oluşturma akışı	Standart Özellikler	UCP Özellikleri
Uygulama Değiştirme (App Flip)	Önerilen	Önerilen
Basitleştirilmiş bağlama	Önerilen	Önerilen
OAuth bağlantısı	Zorunlu (Yedek)	Zorunlu (Yedek)
OAuth 2.1	Önerilen	Önerilen

• Yalnızca gerekli verileri paylaşmak için özel kapsamlar tanımlayarak kullanıcı gizliliğini iyileştirin. Verilerinin nasıl kullanıldığını net bir şekilde tanımlayarak kullanıcıların güvenini artırın.

• Platformunuzda barındırılan verilere ve hizmetlere erişim, hesapların bağlantısı kaldırılarak iptal edilebilir. İsteğe bağlı token iptal etme uç noktası uygulayarak Google'ın başlattığı etkinliklerle senkronize kalabilir, Çapraz Hesap Koruma (RISC) ile de platformunuzda gerçekleşen tüm bağlantı kaldırma etkinliklerini Google'a bildirebilirsiniz.

Not: Google Kimlik Platformu ile ilgili OAuth 2.0 belgelerinin çoğu, kullanıcılarınızın Google Hesapları ile nasıl oturum açabileceğini ve onlar adına Google API'lerini çağırmak için nasıl yetki alabileceğinizi kapsar. Google Hesap Bağlama, Google hizmeti kullanıcısının platformunuzda kimlik doğrulaması yapmasına ve hizmetinizin API'lerini çağırmasına izin verme işleminin tersi olan durumu kapsar. Google API'lerine erişmek için OAuth 2.0'ı kullanmak istiyorsanız OAuth 2.0 istemci dokümanlarına bakın.

Hesap bağlama akışları

Üç Google Hesabı bağlantısı akışı vardır. Bunların tümü OAuth tabanlıdır ve OAuth 2.0 uyumlu yetkilendirme ile jeton değişimi uç noktalarını yönetmenizi veya kontrol etmenizi gerektirir.

Bağlantı oluşturma süreci sırasında, hesap sahiplerinin hesaplarını bağlama ve verileri paylaşma iznini aldıktan sonra Google'a tek tek Google Hesapları için erişim jetonları verirsiniz.

OAuth bağlantısı

Bu, kullanıcıları bağlantı oluşturmak için web sitenize yönlendiren OAuth bağlantı oluşturma akışıdır. Kullanıcı, hesabında oturum açmak için web sitenize yönlendirilir. Oturum açtıktan sonra kullanıcı, hizmetinizdeki verilerinin Google ile paylaşılmasına izin verir. Bu noktada, kullanıcının Google Hesabı ile hizmetiniz bağlanır.

OAuth bağlantısı, yetkilendirme kodu ve örtülü OAuth akışlarını destekler. Hizmetiniz, dolaylı akış için OAuth 2.0 uyumlu bir yetkilendirme uç noktasına sahip olmalı ve yetkilendirme kodu akışı kullanılırken hem yetkilendirme hem de jeton değişimi uç noktası sunmalıdır.

Dikkat: MCP, UCP ve aracı odaklı akışlarda OAuth 2.1 zorunludur ve örtülü akış desteklenmez. Bunun yerine yetkilendirme kodu akışını kullanın.

Not: OAuth bağlama, tüm hesap bağlama entegrasyonları için gereklidir. Bu yöntem, Uygulama Geçişi ve Basitleştirilmiş akışlar için yedek yöntemdir.

Şekil 1. OAuth bağlama ile kullanıcının telefonunda hesap bağlama

OAuth tabanlı uygulama bağlama (Uygulama Bağlama)

Kullanıcıları bağlantı oluşturmak için uygulamanıza yönlendiren bir OAuth akışı.

OAuth tabanlı Uygulama Geçişi Bağlantısı, kullanıcıları doğrulanmış Android veya iOS mobil uygulamalarınız ile Google'ın platformu arasında geçiş yaparken yönlendirerek önerilen veri erişimi değişikliklerini incelemelerini ve platformunuzdaki hesaplarını Google Hesaplarıyla bağlamak için izin vermelerini sağlar. Uygulama Geçişi'ni etkinleştirmek için hizmetiniz OAuth bağlantısını veya yetkilendirme kodu akışını kullanarak OAuth tabanlı Google ile Oturum Açma Bağlantısı'nı desteklemelidir.

Uygulama Değiştirme özelliği hem Android hem de iOS'te desteklenir.

İşleyiş şekli:

Google uygulaması, uygulamanızın kullanıcının cihazında yüklü olup olmadığını kontrol eder:

• Uygulama bulunursa kullanıcı uygulamanıza "yönlendirilir". Uygulamanız, kullanıcının hesabı Google'a bağlaması için izin alır ve ardından Google yüzeyine "geri yönlendirilir".
• Uygulama bulunamazsa veya uygulama bağlama bağlantı oluşturma süreci sırasında bir hata oluşursa kullanıcı, basitleştirilmiş veya OAuth bağlantı oluşturma akışına yönlendirilir.

Şekil 2. Uygulama Geçişi ile kullanıcının telefonunda hesap bağlama

OAuth tabanlı basitleştirilmiş bağlama ("Basitleştirilmiş")

OAuth tabanlı Google ile Oturum Açma özelliği, bağlantı oluşturma sürecini kolaylaştırır. Bu özellik, OAuth bağlantısının üzerine Google ile Oturum Açma'yı ekleyerek kullanıcıların Google platformundan ayrılmadan bağlantı oluşturma sürecini tamamlamasına olanak tanır. Böylece, sorunlar ve kullanıcı kaybı azaltılır. OAuth tabanlı basitleştirilmiş bağlama, Google ile oturum açma ve OAuth bağlamayı birleştirerek sorunsuz oturum açma, hesap oluşturma ve hesap bağlama ile en iyi kullanıcı deneyimini sunar. Hizmetiniz, OAuth 2.0 uyumlu yetkilendirme ve jeton değişimi uç noktalarını desteklemelidir. Ayrıca, jeton değişimi uç noktanız JSON Web Token (JWT) onaylarını desteklemeli ve check, create ve get amaçlarını uygulamalıdır.

Not: Kullanıcı bu akış sırasında Google yüzeyinden hiç ayrılmaz. Bu nedenle, akışın düzgün çalışması için Google, 3. taraf adına izin göstermelidir.

İşleyiş şekli:

Google, kullanıcı hesabını onaylar ve bu bilgileri size iletir:

• Veritabanınızda kullanıcı için bir hesap varsa kullanıcı, Google Hesabı'nı hizmetinizdeki hesabıyla başarıyla bağlar.
• Veritabanınızda kullanıcı için bir hesap yoksa kullanıcı, Google'ın sağladığı onaylanmış bilgilerle (e-posta, ad ve profil resmi) yeni bir 3. taraf hesabı oluşturabilir veya başka bir e-postayla oturum açıp bağlantı oluşturmayı seçebilir (Bunun için OAuth bağlantısını kullanarak hizmetinizde oturum açması gerekir).

Şekil 3. Basitleştirilmiş Bağlantı ile kullanıcının telefonunda hesap bağlama

Hangi akışı kullanmalısınız?

Kullanıcıların en iyi bağlantı deneyimini elde etmesini sağlamak için tüm akışları uygulamanızı öneririz. Basitleştirilmiş ve uygulama bağlama akışları, kullanıcılar bağlantı oluşturma sürecini çok az adımda tamamlayabildiğinden bağlantı oluşturma sürecindeki zorlukları azaltır. OAuth bağlantı oluşturma akışı en az çaba gerektiren akıştır ve diğer bağlantı oluşturma akışlarını ekleyebileceğiniz iyi bir başlangıç noktasıdır.

Not: Diğer akışlar için yedekleme olduğundan, tüm entegrasyonlarda OAuth bağlantı akışı gereklidir.

Jetonlarla çalışma

Google Hesabı bağlantısı, OAuth 2.0 endüstri standardını temel alır.

Hesap sahiplerinin hesaplarını bağlama ve veri paylaşma iznini aldıktan sonra Google'a bireysel Google Hesapları için erişim jetonları verirsiniz.

Jeton türleri

OAuth 2.0, kullanıcı aracısı, istemci uygulaması ve OAuth 2.0 sunucusu arasında iletişim kurmak için jeton adı verilen dizeleri kullanır.

Hesap bağlama sırasında üç tür OAuth 2.0 jetonu kullanılabilir:

• Yetkilendirme kodu. Erişim ve yenileme jetonuyla değiştirilebilen kısa ömürlü bir jeton. Google, güvenlik nedeniyle tek kullanımlık veya çok kısa ömürlü bir kod almak için yetkilendirme uç noktanızı arar.

• Erişim jetonu. Sahibine bir kaynağa erişim izni veren jeton. Bu jetonun kaybolmasından kaynaklanabilecek riski sınırlamak için jetonun sınırlı bir geçerlilik süresi vardır ve genellikle yaklaşık bir saat sonra geçerliliği sona erer.

• Yenileme jetonu. Erişim jetonunun süresi dolduğunda yeni bir erişim jetonuyla değiştirilebilen uzun ömürlü bir jeton. Hizmetiniz Google ile entegre olduğunda bu jeton yalnızca Google tarafından saklanır ve kullanılır. Google, yenileme jetonlarını erişim jetonlarıyla değiştirmek için jeton değişimi uç noktanızı çağırır. Bu jetonlar da kullanıcı verilerine erişmek için kullanılır.

Jeton işleme

Kümelenmiş ortamlardaki ve istemci-sunucu değişimlerindeki yarış koşulları, jetonlarla çalışırken karmaşık zamanlama ve hata işleme senaryolarına neden olabilir. Örneğin:

• Yeni bir erişim jetonu isteği alırsınız ve yeni bir erişim jetonu verirsiniz. Aynı anda, önceki ve süresi dolmamış erişim jetonu kullanılarak hizmetinizin kaynağına erişim isteği alırsınız.
• Yenileme jetonu yanıtınız henüz Google tarafından alınmamıştır (veya hiç alınmamıştır). Bu sırada, daha önce geçerli olan yenileme jetonu Google'dan gelen bir istekte kullanılır.

İstekler ve yanıtlar herhangi bir sırada gelebilir veya kümede çalışan eşzamansız hizmetler, ağ davranışı ya da başka nedenlerle hiç gelmeyebilir.

Hem sizin hem de Google'ın jeton işleme sistemleri içinde ve arasında anında ve tamamen tutarlı paylaşılan durum garanti edilemez. Kısa bir süre içinde sistemler arasında veya sistemler içinde birden fazla geçerli ve süresi dolmamış jeton bulunabilir. Kullanıcılar üzerindeki olumsuz etkiyi en aza indirmek için aşağıdakileri yapmanızı öneririz:

• Daha yeni bir jeton verildikten sonra bile süresi dolmamış erişim jetonlarını kabul edin.
• Yenileme jetonu döndürme işlemine alternatifler kullanın.
• Aynı anda geçerli olan birden fazla erişim ve yenileme jetonunu destekleyin. Güvenlik için jeton sayısını ve jeton ömrünü sınırlamanız gerekir.

Bakım ve kesinti yönetimi

Bakım sırasında veya planlanmamış kesintilerde Google, erişim ve yenileme jetonlarını almak için yetkilendirme veya jeton değişimi uç noktalarınızı çağıramayabilir.

Uç noktalarınız 503 hata kodu ve boş gövdeyle yanıt vermelidir. Bu durumda Google, başarısız olan jeton değişimi isteklerini sınırlı bir süre boyunca yeniden dener. Google'ın daha sonra yenileme ve erişim jetonları alabildiği durumlarda, başarısız olan istekler kullanıcılara görünmez.

Uyarı: Bakım veya kesinti sırasında 400 hata kodu ve {"error": "invalid_grant"} gövdesi döndürmeyin. Bu işlem, daha önce verilmiş jetonları siler ve kullanıcıların hesaplarını yeniden bağlamasını gerektirir.

Erişim jetonu istekleri başarısız olursa kullanıcı tarafından başlatılan isteklerde görünür bir hata oluşur. Örtülü OAuth 2.0 akışı kullanılıyorsa kullanıcıların bağlantı hatalarını yeniden denemeleri gerekir.

Öneriler

Bakımın etkisini en aza indirmek için birçok çözüm vardır. Göz önünde bulundurabileceğiniz bazı seçenekler:

• Mevcut hizmetinizi koruyun ve sınırlı sayıda isteği yeni güncellenen hizmetinize yönlendirin. Tüm istekleri yalnızca beklenen işlevselliği onayladıktan sonra taşıyın.

• Bakım süresi boyunca jeton isteği sayısını azaltın:

  • Bakım dönemlerini erişim jetonunun kullanım ömründen daha kısa tutun.

  • Erişim jetonunun kullanım ömrünü geçici olarak artırın:

    1. Jetonun kullanım ömrünü bakım süresinden daha uzun olacak şekilde artırın.
    2. Erişim jetonunuzun kullanım ömrünün iki katı kadar bekleyin. Bu sayede kullanıcılar kısa ömürlü jetonları daha uzun ömürlü jetonlarla değiştirebilir.
    3. Bakım moduna girin.
    4. Jeton isteklerine 503 hata kodu ve boş gövdeyle yanıt verin.
    5. Bakım modundan çıkın.
    6. Jetonun kullanım ömrünü tekrar normale düşürün.

Kalıcı Bağlantı

Kalıcı bağlantı, kararlı entegrasyonlar için temel bir gerekliliktir. Bu, geçici ağ hataları veya düzenli kimlik bilgisi yenileme işlemleri sırasında bile kullanıcı hesaplarının bağlı kalmasını sağlar.

Kalıcı bağlantı oluşturmayı uygulamak için "kayan pencere" yaklaşımını kullanın: Mevcut yenileme jetonunun süresini döndürmek yerine uzatın (RFC 6749 Bölüm 6'ya bakın). Bu, yeni bir yenileme jetonu yayınlandığında ancak Google tarafından başarıyla alınmadığında veya depolanmadığında ortaya çıkabilecek yarış koşullarını ve istenmeyen bağlantı kaldırma işlemlerini önler.

Google ile kaydolma

Hesap bağlama özelliğini etkinleştirmek için OAuth 2.0 kurulumunuzun ayrıntılarını ve kimlik bilgilerini paylaşmanız gerekir. Ayrıntılar için kayıt bölümüne bakın.