Android için Uygulama Çevirme

OAuth 2.0 uygulamanızı tamamladıktan sonra, OAuth tabanlı App Flip yapılandırabilirsiniz. Bu sayede Android kullanıcılarınız, kimlik doğrulama sisteminizdeki hesaplarını kendi Google hesaplarına daha hızlı bağlayabilir. Aşağıdaki bölümlerde, smart home Action'ınız için App Flip'nin nasıl tasarlanacağı ve uygulanacağı açıklanmaktadır.

Tasarım yönergeleri

Bu bölümde, Uygulama çevirme hesabı bağlama izin ekranıyla ilgili tasarım şartları ve öneriler açıklanmaktadır. Google uygulamanızı çağırdıktan sonra, uygulamanız kullanıcılara izin ekranını gösterir.

Koşullar

  1. Kullanıcının hesabının Google Home veya Google Asistan gibi belirli bir Google ürününe değil Google'a bağlı olduğunu bildirmeniz gerekir.

Öneriler

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

  1. Google'ın Gizlilik Politikası'nı görüntüleyin. İzin ekranına Google'ın Gizlilik Politikası'nın bir bağlantısını ekleyin.

  2. Paylaşılacak veriler. Google'a hangi verileri neden ihtiyaç duyduğunu kullanıcılara açık ve net bir şekilde açıklayın.

  3. Harekete geçirici mesaj net. İzin ekranınızda "Kabul et ve bağla" gibi net bir harekete geçirici mesaj belirtin. Bunun nedeni, kullanıcıların hesaplarını bağlamak için Google ile hangi verileri paylaşmaları gerektiğini anlamalarıdır.

  4. İptal etme yetkisi. Kullanıcılar bağlantı oluşturmamayı tercih ettiklerinde geri dönme veya iptal etme yolu sağlayın.

  5. Bağlantıyı kaldırma olanağı. Kullanıcıların bağlantısını kaldırabilecekleri bir mekanizma sunun (ör. platformunuzdaki hesap ayarlarının URL'si). Alternatif olarak, kullanıcıların bağlı hesaplarını yönetebilecekleri bir Google Hesabı bağlantısı ekleyebilirsiniz.

  6. Kullanıcı hesabını değiştirme yetkisi. Kullanıcıların hesaplarını değiştirmesi için bir yöntem önerin. Bu, özellikle kullanıcıların birden fazla hesaba sahip 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ük akış ile istediğiniz hesapta oturum açabilir.

  7. Logonuzu ekleyin. Şirket logonuzu izin ekranında gösterin. Logonuzu yerleştirmek için stil yönergelerinizi kullanın. Google logosunu da görüntülemek istiyorsanız Logolar ve ticari markalar bölümüne bakın.

Bu şekilde, kullanıcı rızası ekranı tasarlarken uymanız gereken bireysel önlemler ve öneriler içeren örnek bir izin ekranı gösterilmektedir.
Şekil 1: Hesap bağlama izin ekranı tasarım yönergeleri.

OAuth tabanlı Uygulama Çevirme için kurulum

Aşağıdaki bölümlerde OAuth tabanlı Uygulama Çevirisi için ön koşullar ve App Flip projenizin Actions konsolunda nasıl yapılandırılacağı açıklanmaktadır.

Akıllı ev İşlemi oluşturun ve OAuth 2.0 sunucusu ayarlayın

Uygulama Dönüşümü'nü yapılandırmadan önce aşağıdakileri yapmanız gerekir:

  • Bir OAuth 2.0 sunucusu ayarlayın. OAuth sunucusu ayarlama hakkında daha fazla bilgi için OAuth 2.0 sunucusu uygulama başlıklı makaleye bakın.
  • Bir İşlem oluşturun. İşlem oluşturmak için Actions projesi oluşturma başlıklı makaledeki talimatları uygulayın.

Actions Console'da Uygulama Dönüşümü'nü yapılandırma

Aşağıdaki bölümde, Çeviri Konsolu'nda Uygulama Çevirme'nin nasıl yapılandırılacağı açıklanmaktadır.

  1. OAuth İstemci Bilgileri altındaki tüm alanları doldurun. (App Flip desteklenmiyorsa normal OAuth yedek olarak kullanılır.)
  2. Uygulamanızı hesap bağlama için kullanma (isteğe bağlı) bölümünde, Android için etkinleştir'i işaretleyin.
  3. Aşağıdaki alanları doldurun:
    • Uygulama Kimliği. Uygulama kimliği, uygulamanız için ayarladığınız benzersiz bir kimliktir.
    • Uygulama imzası. Android uygulamalarının yüklenebilmesi için ortak anahtar sertifikasıyla "imzalanması" gerekir. Uygulama imzanızı alma hakkında bilgi edinmek için İstemcinizin Kimliğini Doğrulama başlıklı makaleye bakın.
    • Yetkilendirme amacı. Bu alana amaç işleminizi belirten bir dize girin.
  4. İsteğe bağlı olarak istemcinizi yapılandırmak istiyorsanız kapsamlar ekleyin ve İstemcinizi yapılandırın (isteğe bağlı) bölümünde Kapsam ekle'yi tıklayın.
  5. Kaydet'i tıklayın.

Android uygulamalarınızda uygulama çevirme özelliğini kullanın

Uygulama Dönüşümü'nü uygulamak için Google'dan bir derin bağlantıyı kabul etmek üzere uygulamanızdaki kullanıcı yetkilendirme kodunu değiştirmeniz gerekir.

OAuth tabanlı Uygulama Çevirisi bağlantı (App Flip), Android uygulamanızı Google Hesabı Bağlantı akışına ekler. Geleneksel bir hesap bağlama akışı, kullanıcının tarayıcıdaki kimlik bilgilerini girmesini gerektirir. App Flip'i kullanmak, Android uygulamanızda kullanıcı oturumlarını erteler. Böylece 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 App Flip'i uygulamak için minimum miktarda kod değişikliği yapmanız gerekir.

Bu dokümanda, Android uygulamanızı App Flip'i destekleyecek şekilde nasıl değiştireceğinizi öğreneceksiniz.

Örneği deneyin

Uygulama çevirme bağlantılı örnek uygulama, Android'de Uygulama Çevirisi ile uyumlu hesap bağlama entegrasyonunu gösterir. Bu uygulamayı kullanarak, Google Mobil uygulamalarından gelen Uygulama Takibi amacına nasıl yanıt vereceğinizi doğrulayabilirsiniz.

Örnek uygulama, Android için Uygulama Kaydırma Test Aracı ile entegre edilecek şekilde önceden yapılandırılmıştır. Google Play ile Hesap bağlamayı yapılandırmadan önce Android uygulamanızın Uygulama Dönüşümü ile entegrasyonunu doğrulamak için bu yöntemi kullanabilirsiniz. Bu uygulama, Uygulama Çevirisi etkinleştirildiğinde Google mobil uygulamaları tarafından tetiklenen niyeti simüle eder.

İşleyiş şekli

Uygulama çevirme 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üklenen uygulamanın doğru uygulama olduğunu doğrulamak için paket imza kontrolü kullanır.
  3. Google uygulaması, uygulamanızda atanmış bir etkinlik başlatmak için bir niyet oluşturur. Bu niyet, bağlantı oluşturmak için gereken ek verileri içerir. Ayrıca, bu niyeti Android çerçevesi aracılığıyla çözerek uygulamanızın Uygulama Çevirisini 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 müşteri kimliğini kontrol eder.
  5. Uygulamanız OAuth 2.0 sunucunuzdan bir yetkilendirme kodu istiyor. Bu akışın sonunda, Google uygulamasına bir yetkilendirme kodu veya bir hata döndürülür.
  6. Google uygulaması sonucu alır ve hesap bağlama ile 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ı App Flip'i destekleyecek şekilde değiştirme

App Flip'i desteklemek için Android uygulamanızda aşağıdaki kod değişikliklerini yapın:

  1. AndroidManifest.xml dosyanıza, Uygulama Dönüşümü Niyeti 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. Arayan uygulamanın imzasını doğrulayın.

    private fun verifyFingerprint(
        expectedPackage: String,
        expectedFingerprint: String,
        algorithm: String
): Boolean {

    callingActivity?.packageName?.let {
        if (expectedPackage == it) {
            val packageInfo =
                packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
            val signatures = packageInfo.signatures
            val input = ByteArrayInputStream(signatures[0].toByteArray())

            val certificateFactory = CertificateFactory.getInstance("X509")
            val certificate =
                certificateFactory.generateCertificate(input) as X509Certificate
            val md = MessageDigest.getInstance(algorithm)
            val publicKey = md.digest(certificate.encoded)
            val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }

            return (expectedFingerprint == fingerprint)
        }
    }
    return false
}

  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 = "<google-app-package-name>"
private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
private const val ALGORITHM = "SHA-256"
...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {

        // ...authorize the user...
    }
}

  4. Yetkilendirme işlemi başarıyla tamamlandığında, 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. Bir hata oluştuysa bunun yerine bir 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()

Lansman amacının içeriği

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

  • CLIENT_ID (String): Google client_id uygulamanız altında kaydedildi.
  • 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() yöntemini kullanarak uygulamanızda ayarlanır. Bu veriler arasında şunlar bulunur:

  • 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: Başarılı olduğunu gösterir; bir yetkilendirme kodu döndürülür.
    • Activity.RESULT_CANCELLED: Kullanıcının işlemi iptal ettiğini gösterir. Bu durumda Google uygulaması yetkilendirme URL'nizi kullanarak hesap bağlamayı dener.
    • -2: Bir hata olduğunu gösterir. Farklı hata türleri aşağıda açıklanmıştır.
  • ERROR_TYPE (int): Aşağıdaki değerlerden birini alan hatanın türü:
    • 1: Kurtarılabilir hata: Google uygulaması, yetkilendirme URL'sini kullanarak hesap bağlamayı deneyecek.
    • 2: Kurtarılamaz hata: Google uygulaması hesap bağlama işlemini iptal ediyor.
    • 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ın okuyabileceği durum mesajı.

AUTHORIZATION_CODE için bir değer beklenir resultCode == Activity.RESULT_OK. Diğer tüm durumlarda AUTHORIZATION_CODE değerinin boş olması gerekir. resultCode == -2 ise ERROR_TYPE değerinin doldurulması beklenir.

Hata kodları tablosu

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

Hata kodu Anlamı İyileştirilebilir 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 üzere hata sonucunu setResult aracılığıyla döndürmeniz gerekir.

Cihazınızda Uygulama Çevirme işlevini test etme

Konsolda ve uygulamanızda İşlem İşlemi oluşturup Uygulama Çevirisini yapılandırdınız. Şimdi de mobil cihazınızda Uygulama Çevirisini test edebilirsiniz. Uygulama Dönüşümü'nü test etmek için Google Asistan uygulamasını veya Google Home uygulamasını kullanabilirsiniz.

Asistan uygulamasında Uygulama Dönüşümü'nü test etmek için aşağıdaki adımları uygulayın:

  1. Actions Console'a gidip projenizi seçin.
  2. Üst gezinme menüsündeki Test et'i tıklayın.
  3. Asistan uygulamasından hesap bağlama akışını tetikleyin:
    1. Google Asistan uygulamasını açın.
    2. Ayarlar'ı tıklayın.
    3. Asistan sekmesinde Ev Kontrolü'nü tıklayın.
    4. Ekle(+) seçeneğini tıklayın.
    5. Sağlayıcı listesinden İşleminizi seçin. Listenin başında "[test]" öneki bulunur. Listeden [test] işleminizi seçtiğinizde uygulamanız açılır.
    6. Uygulamanızın kullanıma sunulduğunu doğrulayın ve yetkilendirme akışınızı test etmeye başlayın.

Home uygulamasını kullanarak Uygulama Çevirme özelliğini test etmek için aşağıdaki adımları uygulayın:

  1. Actions Console'a gidip projenizi seçin.
  2. Üst gezinme menüsündeki Test et'i tıklayın.
  3. Home uygulamasından hesap bağlama akışını tetikleyin:
    1. Google Home uygulamasını açın.
    2. + düğmesini tıklayın.
    3. Cihazı kur'u tıklayın.
    4. Hazır bir kurulumunuz var mı? seçeneğini tıklayın.
    5. Sağlayıcı listesinden akıllı ev İşleminizi seçin. Listenin başında "[test]" öneki bulunur. Listeden [test] işleminizi seçtiğinizde uygulamanız açılır.
    6. Uygulamanızın kullanıma sunulduğunu doğrulayın ve yetkilendirme akışınızı test etmeye başlayın.
Önceki
Actions projesi oluşturma
Sonraki
Tanımlama ve senkronize etme