Android için Uygulama Çevirme

OAuth 2.0 uygulamanız olduğunda, isteğe bağlı olarak OAuth tabanlı App Flip yapılandırabilirsiniz. Bu sayede Android kullanıcılarınız, kimlik doğrulama sisteminizdeki hesaplarını Google Hesaplarına daha hızlı bağlayabilir. Aşağıdaki bölümlerde, Android üzerinde Cloud-to-cloud entegrasyonunuz için App Flip tasarlama ve uygulama adımları açıklanmaktadır.

Tasarım yönergeleri

Bu bölümde, Uygulama Değiştirme hesap bağlama izin ekranıyla ilgili tasarım şartları ve önerileri açıklanmaktadır. Google, uygulamanızı çağırdıktan sonra uygulamanız kullanıcıya izin ekranını gösterir.

Şartlar

1. "Bağlandıktan sonra Google, cihazlarınızı kontrol etme iznine sahip olur." gibi bir Google yetkilendirme beyanınız olmalıdır.
2. Kullanıcı hesabının Google Home veya Google Asistan gibi belirli bir Google ürününe değil Google'a bağlandığını belirtmeniz gerekir.
3. İzin ekranınızda net bir harekete geçirici mesaj belirtmeniz ve bağlama işlemi için "Kabul et ve bağla" ifadesini kullanmanız gerekir. Bunun nedeni, kullanıcıların hesaplarını bağlamak için Google ile hangi verileri paylaşmaları gerektiğini anlamaları gerektiğidir.
4. Kullanıcılar bağlantı oluşturmamayı seçerse geri dönmelerine, reddetmelerine veya iptal etmelerine olanak tanımanız gerekir. İptal işlemi için "İptal" kelimesini kullanın.
5. Şu iş akışını uygulamanız gerekir: "Kabul et ve bağla"yı tıkladıktan sonra bağlama işleminin başarılı olduğunu göstermeli ve kullanıcıyı otomatik olarak Google Home uygulamasına yönlendirmelisiniz. Kullanıcı, işleminizle birlikte Google Home uygulamasında bağlı cihazı görmelidir. "İptal"i tıkladıktan sonra kullanıcıyı Google Home uygulamasına yönlendirmeniz gerekir.

Öneriler

Aşağıdakileri yapmanızı öneririz:

1. Google'ın Gizlilik Politikası'nı gösterin. Kullanıcı rızası ekranına Google'ın Gizlilik Politikası bağlantısını ekleyin.

2. Paylaşılacak veriler. Google'ın hangi kullanıcı verilerini neden istediğini kullanıcıya bildirmek için açık ve net bir dil kullanın.

3. Bağlantıyı kaldırma özelliği. Kullanıcılara bağlantıyı kaldırma mekanizması sunun. Örneğin, platformunuzdaki hesap ayarlarına yönlendiren bir URL. Alternatif olarak, kullanıcıların bağlı hesaplarını yönetebileceği Google Hesabı'na bir bağlantı ekleyebilirsiniz.

4. Kullanıcı hesabını değiştirme Kullanıcılara hesaplarını değiştirmeleri için bir yöntem önerin. Bu özellik, özellikle kullanıcıların birden fazla hesabı olduğu durumlarda faydalıdır.

   • Kullanıcının hesap değiştirmek için izin ekranını kapatması gerekiyorsa Google'a kurtarılabilir bir hata gönderin. Böylece kullanıcı, OAuth bağlantısı ve örtülü akışla istediği hesapta oturum açabilir.

5. Logonuzu ekleyin. İzin ekranında şirket logonuzu gösterin. Logonuzu yerleştirmek için stil kurallarınızı kullanın. Google'ın logosunu da göstermek istiyorsanız Logolar ve ticari markalar bölümüne bakın.

OAuth tabanlı App Flip için kurulum yapın

Aşağıdaki bölümlerde, OAuth tabanlı uygulama bağlama için ön koşullar ve Google Home Developer Console'da uygulama bağlama projenizi nasıl yapılandıracağınız açıklanmaktadır.

Buluttan buluta entegrasyon oluşturma ve OAuth 2.0 sunucusu oluşturma

App Flip hizmetini yapılandırmadan önce aşağıdakileri yapmanız gerekir:

• OAuth 2.0 sunucusu oluşturun. OAuth sunucusu oluşturma hakkında daha fazla bilgi için OAuth 2.0 sunucusu uygulama başlıklı makaleyi inceleyin.
• Buluttan buluta entegrasyon oluşturun. Entegrasyon oluşturmak için Buluttan buluta entegrasyon oluşturma başlıklı makaledeki talimatları uygulayın.

Developer Console'da Uygulama Bağlama'yı yapılandırma

Aşağıdaki bölümde, Geliştirici Konsolu'nda Uygulama Bağlama'nın nasıl yapılandırılacağı açıklanmaktadır.

1. Hesap Bağlantısı bölümündeki tüm zorunlu(*) alanları doldurun. (Uygulama Bağlama desteklenmiyorsa yedek olarak normal OAuth kullanılır.)
2. Cloud karşılama URL'si için bir URL girin. Bulut karşılama URL'si, akıllı ev amaçlarınızı işlemek için kullanılır. Yerel sipariş karşılama'yı işaretleyin.
3. Uygulama Bağlama (isteğe bağlı) bölümünde Android uygulaması'nı işaretleyin.
4. Aşağıdaki alanları doldurun:
• Uygulama kimliği. Uygulama kimliği, uygulamanız için ayarladığınız benzersiz bir kimliktir.
• Uygulama imzalama. Android uygulamalarının yüklenebilmesi için ortak anahtar sertifikasıyla "imzalanması" gerekir. Uygulama imzanızı alma hakkında bilgi için İstemcinizin Kimliğini Doğrulama başlıklı makaleyi inceleyin.
• Yetkilendirme amacı. Bu alana intent işleminizi belirten bir dize girin.
5. İstemcinizi isteğe bağlı olarak yapılandırmak istiyorsanız kapsam ekleyin ve Kapsamlar (isteğe bağlı) bölümünde Kapsam ekle'yi tıklayın.
6. İstemciniz gerektiriyorsa Google'ın istemci kimliğini ve gizli anahtarını HTTP temel kimlik doğrulama üstbilgisi aracılığıyla iletmesini sağlayın'ı seçin.

Artık Android uygulamanızda App Flip özelliğini uygulamak için sonraki bölüme geçebilirsiniz.

Yerel uygulamalarınızda App Flip uygulayın

App Flip özelliğini uygulamak için uygulamanızdaki kullanıcı yetkilendirme kodunu, Google'dan gelen derin bağlantıyı kabul edecek şekilde değiştirmeniz gerekir.

OAuth tabanlı Uygulama Bağlama (App Flip), Android uygulamanızı Google Hesabı Bağlantısı akışına ekler. Geleneksel hesap bağlama akışında kullanıcının kimlik bilgilerini tarayıcıya girmesi gerekir. Uygulama Bağlama'nın kullanılması, kullanıcı oturum açma işlemini Android uygulamanıza erteler. Bu sayede mevcut yetkilendirmelerden yararlanabilirsiniz. Kullanıcı uygulamanızda oturum açtıysa hesabını bağlamak için kimlik bilgilerini yeniden girmesi gerekmez. Android uygulamanızda Uygulama Bağlama'yı uygulamak için minimum miktarda kod değişikliği gerekir.

Bu dokümanda, Android uygulamanızı Uygulama Bağlama'yı destekleyecek şekilde nasıl değiştireceğinizi öğreneceksiniz.

Örneği deneyin

Uygulama Bağlama bağlantısı örnek uygulaması, Android'de Uygulama Bağlama ile uyumlu bir hesap bağlama entegrasyonunu gösterir. Bu uygulamayı, Google mobil uygulamalarından gelen bir Uygulama Bağlama intent'ine nasıl yanıt verileceğini doğrulamak için kullanabilirsiniz.

Örnek uygulama, Android için Uygulama Bağlama Test Aracı ile entegre olacak şekilde önceden yapılandırılmıştır. Bu aracı, Google ile hesap bağlantısını yapılandırmadan önce Android uygulamanızın Uygulama Bağlama ile entegrasyonunu doğrulamak için kullanabilirsiniz. Bu uygulama, Uygulama Bağlama etkinleştirildiğinde Google mobil uygulamaları tarafından tetiklenen intent'i simüle eder.

İşleyiş şekli

Uygulama Bağlama entegrasyonu gerçekleştirmek için aşağıdaki adımlar gereklidir:

1. Google uygulaması, paket adını kullanarak uygulamanızın cihazda yüklü olup olmadığını kontrol eder.
2. Google uygulaması, yüklü uygulamanın doğru uygulama olduğunu doğrulamak için paket imza kontrolü kullanır.
3. Google uygulaması, uygulamanızda belirli bir etkinliği başlatmak için bir intent oluşturur. Bu intent, bağlantı için gereken ek verileri içerir. Ayrıca, bu intent'i Android çerçevesi üzerinden çözerek uygulamanızın Uygulama Bağlama'yı destekleyip desteklemediğini kontrol eder.
4. Uygulamanız, isteğin Google uygulamasından geldiğini doğrular. Bunun için uygulamanız, paket imzasını ve sağlanan istemci kimliğini kontrol eder.
5. Uygulamanız, OAuth 2.0 sunucunuzdan bir yetkilendirme kodu ister. Bu akışın sonunda Google uygulamasına bir yetkilendirme kodu veya hata döndürür.
6. Google uygulaması sonucu alır ve hesap bağlama işlemine devam eder. Yetkilendirme kodu sağlanırsa jeton değişimi, tarayıcı tabanlı OAuth bağlantı akışında olduğu gibi sunucudan sunucuya gerçekleşir.

Android uygulamanızı uygulama bağlamayı destekleyecek şekilde değiştirme

Uygulama Bağlama'yı desteklemek için Android uygulamanızda aşağıdaki kod değişikliklerini yapın:

1. AndroidManifest.xml dosyanıza, Uygulama Bağlama Intent'i alanına girdiğiniz değerle eşleşen bir işlem dizesi içeren bir <intent-filter> ekleyin.

   <activity android:name="AuthActivity">
     <!-- Handle the app flip intent -->
     <intent-filter>
       <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
       <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
   </activity>
   

2. Arama uygulamasının imzasını doğrulayın.

   Kullanıcıların hesap bağlamak için kullanabileceği tüm Google uygulamalarının paket adını ve imzasını eşleştirmeniz gerekir. Örneğin, Google Home ve Arama uygulamalarıyla bağlantı oluşturmak için bunların paket adlarını ve imzalarını ekleyin:

   • Paket adı: com.google.android.apps.chromecast.app
   • Orijinal SHA-256 köken sertifikası: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
   • Rotasyonu yapılmış Google Play Uygulama İmzalama SHA-256 sertifikası: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

   ve

   • Paket adı: com.google.android.googlequicksearchbox
   • İmza: F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

   Akıllı ev bağlama istekleri doğrudan Google Home app (GHA) tarafından başlatılır. Uygulamanız arayanları kısıtlıyor ve daha önce yalnızca Google Arama uygulamasına izin veriyorduysa Uygulama Bağlama'nın başarılı olmaya devam etmesi için com.google.android.apps.chromecast.app ve SHA-256 sertifikalarını izin verilenler listenize eklemeniz gerekir.

   private fun verifyFingerprint(
       expectedPackage: String,
       expectedFingerprints: List<String>
   ): Boolean {
       val callingPackage = callingActivity?.packageName ?: return false
       if (callingPackage != expectedPackage) return false
       return expectedFingerprints.any { hex ->
           val sha256Bytes =
               hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
           packageManager.hasSigningCertificate(
               callingPackage,
               sha256Bytes,
               PackageManager.CERT_INPUT_SHA256
           )
       }
   }
   

3. İstemci kimliğini intent parametrelerinden çıkarın ve istemci kimliğinin beklenen değerle eşleştiğini doğrulayın.

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
   // Original lineage certificate (3D:7A...) and active rotated
   // Play App Signing certificate (5A:AD...)
   private val EXPECTED_FINGERPRINTS = listOf(
       "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
       "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
   )
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {
   
           // ...authorize the user...
       }
   }
   

4. Yetkilendirme başarılı olursa elde edilen yetkilendirme kodunu Google'a geri gönderin.

   // Successful result
   val data = Intent().apply {
       putExtra("AUTHORIZATION_CODE", authCode)
   }
   setResult(Activity.RESULT_OK, data)
   finish()
   

5. Hata oluştuysa bunun yerine hata sonucu döndürün.

   // Error result
   val error = Intent().apply {
       putExtra("ERROR_TYPE", 1)
       putExtra("ERROR_CODE", 1)
       putExtra("ERROR_DESCRIPTION", "Invalid Request")
   }
   setResult(-2, error)
   finish()
   

Başlatma intent'inin içeriği

Uygulamanızı başlatan Android intent'i aşağıdaki alanları içerir:

• CLIENT_ID (String): Uygulamanızda kayıtlı Google client_id.
• SCOPE (String[]): İstenen kapsamların listesi.
• REDIRECT_URI (String): Yönlendirme URL'si.

Yanıt verilerinin içeriği

Google uygulamasına döndürülen veriler, setResult() çağrılarak uygulamanızda ayarlanır. Bu veriler şunları içerir:

• AUTHORIZATION_CODE (String): Yetkilendirme kodu değeri.
• resultCode (int): İşlemin başarılı veya başarısız olduğunu bildirir ve aşağıdaki değerlerden birini alır:
  • Activity.RESULT_OK: İşlemin başarılı olduğunu gösterir. Bir yetkilendirme kodu döndürülür.
  • Activity.RESULT_CANCELLED: Düzeltilebilir bir hata. Kullanıcının işlemi iptal ettiğini gösterir. Bu durumda Google uygulaması, yetkilendirme URL'nizi kullanarak hesap bağlamayı tekrar dener.
  • -2: Bir hata oluştuğunu gösterir. Farklı hata türleri aşağıda açıklanmıştır.
• ERROR_TYPE (int): Hatanın türü. Aşağıdaki değerlerden birini alır:
  • 1: Kurtarılabilir hata: Google uygulaması, yetkilendirme URL'sini kullanarak hesap bağlamayı dener.
  • 2: Düzeltilemeyen hata: Google uygulaması, hesap bağlama işlemini iptal eder.
  • 3: İstek parametreleri geçersiz veya eksik.
• ERROR_CODE (int): Hatanın niteliğini temsil eden bir tam sayı. Her bir hata kodunun ne anlama geldiğini görmek için hata kodları tablosuna bakın.

• ERROR_DESCRIPTION (String, isteğe bağlı): Hatayı açıklayan, kullanıcılar tarafından okunabilen durum mesajı.

resultCode == Activity.RESULT_OK olduğunda AUTHORIZATION_CODE için bir değer beklenir. Diğer tüm durumlarda AUTHORIZATION_CODE değeri boş olmalıdır. resultCode == -2 ise ERROR_TYPE değerinin doldurulması beklenir.

Hata kodları tablosu

Aşağıdaki tabloda farklı hata kodları ve her birinin kurtarılabilir mi yoksa düzeltilemeyen hata mı olduğu gösterilmektedir:

Hata kodu	Anlamı	Kurtarılabilir	Kurtarılamaz
1	INVALID_REQUEST	✔
2	NO_INTERNET_CONNECTION		✔
3	OFFLINE_MODE_ACTIVE	✔
4	CONNECTION_TIMEOUT	✔
5	INTERNAL_ERROR	✔
6	AUTHENTICATION_SERVICE_UNAVAILABLE		✔
8	CLIENT_VERIFICATION_FAILED	✔
9	INVALID_CLIENT	✔
10	INVALID_APP_ID	✔
11	INVALID_REQUEST	✔
12	AUTHENTICATION_SERVICE_UNKNOWN_ERROR		✔
13	AUTHENTICATION_DENIED_BY_USER		✔
14	CANCELLED_BY_USER		✔
15	FAILURE_OTHER		✔
16	USER_AUTHENTICATION_FAILED	✔

Tüm hata kodları için uygun yedeğin tetiklendiğinden emin olmak amacıyla hata sonucunu setResult üzerinden döndürmeniz gerekir.

Cihazınızda App Flip uygulamasını test edin

Buluttan buluta entegrasyon oluşturup konsolda ve uygulamanızda uygulama bağlamayı yapılandırdığınıza göre artık mobil cihazınızda uygulama bağlamayı test edebilirsiniz. Uygulama Bağlama'yı test etmek için Google Home uygulamasını kullanabilirsiniz.

App Flip uygulamasını Google Home uygulamasından test etmek için aşağıdaki adımları uygulayın:

1. Developer Console'a gidip projenizi seçin.
2. Cloud-to-cloud > Test'e gidin.
3. Home uygulamasından hesap bağlama akışını tetikleyin:
1. Google Home app (GHA) uygulamasını açın.
2. + düğmesini tıklayın.
3. Cihazı kur'u tıklayın.
4. Kurulmuş cihazlarınız mı var? seçeneğini tıklayın.
5. Sağlayıcı listesinden buluttan buluta entegrasyonunuzu seçin. Listede "[test]" ön ekiyle gösterilir. Listeden [test] entegrasyonunuzu seçtiğinizde uygulamanız açılır.
6. Uygulamanızın başlatıldığını doğrulayın ve yetkilendirme akışınızı test etmeye başlayın.