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.

令牌类型

OAuth 2.0 使用称为令牌的字符串在用户代理、客户端应用和 OAuth 2.0 服务器之间进行通信。

在帐号关联期间，可以使用三种类型的 OAuth 2.0 令牌：

• 授权代码 。一种短期令牌，可以交换为访问令牌和刷新令牌。出于安全考虑，Google 会调用您的授权端点来获取一次性或短期代码。

• 访问令牌 。一种令牌，用于授予持有者对资源的访问权限。为了限制因丢失此令牌而可能造成的风险，此令牌的生命周期有限，通常会在大约一小时后过期。

• 刷新令牌 。一种长期令牌，当访问令牌过期时，可以交换为新的访问令牌。当您的服务与 Google 集成时，此令牌仅由 Google 存储和使用。Google 会调用您的令牌交换端点，以将刷新令牌交换为访问令牌，而访问令牌又用于访问用户数据。

令牌处理

在集群环境和客户端-服务器交换中，竞争条件可能会导致在使用令牌时出现复杂的时序和错误处理场景。 例如：

• 您收到有关新访问令牌的请求，并签发了新的访问令牌。同时，您收到有关使用之前未过期的访问令牌访问您服务资源的请求。
• Google 尚未收到（或永远不会收到）您的刷新令牌回复。与此同时，之前有效的刷新令牌在 Google 的请求中使用。

由于集群中运行的异步服务、网络行为或其他方式，请求和回复可能会以任何顺序到达，或者根本不会到达。

无法保证您的令牌处理系统和 Google 的令牌处理系统之间以及内部的即时且完全一致的共享状态。在短时间内，多个有效且未过期的令牌可能会在系统内或跨系统共存。为了最大限度地减少对用户的负面影响，我们建议您执行以下操作：

• 接受未过期的访问令牌，即使在签发新令牌后也是如此。
• 使用 刷新令牌轮替的替代方案。
• 支持多个同时有效的访问令牌和刷新令牌。出于安全考虑，您应限制令牌数量和令牌生命周期。

维护和服务中断处理

在维护期间或计划外中断期间，Google 可能无法调用您的授权端点或令牌交换端点来获取访问令牌和刷新令牌。

您的端点应返回 503 错误代码和空正文。在这种情况下，Google 会在有限的时间内重试失败的令牌交换请求。前提是 Google 稍后能够获取刷新令牌和访问令牌，否则用户将无法看到失败的请求。

**警告** ：请勿在维护或中断期间返回 400 错误代码和 {"error": "invalid_grant"} 正文 。这样做会删除之前签发的令牌，并要求用户重新关联其帐号。

如果用户发起的访问令牌请求失败，则会导致显示错误。如果使用隐式 OAuth 2.0 流程，则用户需要重试关联失败。

建议

有很多解决方案可以最大限度地减少维护影响。您可以考虑以下选项：

• 维护现有服务，并将有限数量的请求路由到新更新的服务。仅在确认预期功能后才迁移所有请求。

• 减少维护期间的令牌请求数量：

  • 将维护期限制为小于访问令牌生命周期。

  • 暂时延长访问令牌生命周期：

    1. 将令牌生命周期延长到大于维护期。
    2. 等待访问令牌生命周期的两倍时长，以便用户将短期令牌交换为长期令牌。
    3. 进入维护期。
    4. 使用 503 错误代码和空正文响应令牌请求。
    5. 退出维护期。
    6. 将令牌生命周期缩短回正常水平。

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.