Android'deki Permissions API

Android için Home API'lerini kullanmadan önce uygulamanın, API'de yapı olarak adlandırılan kullanıcının evindeki cihazlara erişme izni olmalıdır. İzinler API'si sayesinde kullanıcı, Google Hesabını kullanarak Home API'leri uygulamalarına evindeki cihazlara erişim izni verebilir.

İzin akışı, kullanıcının Google Home app (GHA) kullanmak zorunda kalmadan, henüz ayarlanmamışsa bir yapı oluşturmasına olanak tanır.

Permissions API'yi entegre edin

Devam etmeden önce Android'de evi başlatma bölümündeki adımları uyguladığınızdan emin olun. Bu adımdaki homeManager örneği, buradaki tüm izin örneklerinde kullanılır.

Öncelikle SDK ile bir ActivityResultCaller kaydedin. Örneğin, örnek uygulama bu durumu şu şekilde ele alır:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

İzinleri kontrol etme

İzin istemeden önce, uygulamanın kullanıcısının yapıya erişim izni verip vermediğini kontrol etmenizi öneririz. Bunun için, PermissionsState değerlerinin Flow değerini elde etmek üzere Home örneğinin hasPermissions() yöntemini çağırın:

val permissionsReadyState =
homeManager.hasPermissions().collect { state ->
    when (state) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
          println("Permissions state unavailable, request permissions")

      PermissionsState.NOT_GRANTED ->
          println("OAuth permission is enabled but not granted yet, request permissions")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

Kontrol PermissionsState veya NOT_GRANTED ya da PERMISSIONS_STATE_UNAVAILABLE döndürürse kullanıcı veya uygulamanın yapıya erişimi yok demektir. Kontrol PermissionsState değerini GRANTED olarak döndürürse ancak structures() için sonraki çağrı yapıları döndürmezse kullanıcı, GHA ayarlar sayfası aracılığıyla uygulamaya erişimi iptal etmiş veya kullanıcının gerekli erişimi yoktur.

İzin iste

Belirli bir yapıdaki yapılara ve cihazlara erişmek için uygulamanıza izin verilmesi gerekir.

Kullanıcı henüz izin vermediyse izin kullanıcı arayüzünü başlatmak ve sonucu işlemek için Home örneğinin requestPermissions() yöntemini kullanın:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

İzinler kullanıcı arayüzünün düzgün şekilde başlatılabilmesi için uygulamanızda OAuth'u ayarlamış olmanız gerekir.

İzin verin

Artık uygulamanızı çalıştırabilir ve kullanıcıdan izin isteyebilirsiniz. İzin verebilecek kullanıcı türü ve izin verilebilecek cihaz türleri, uygulamanızı Google Home Developer Console'ya kaydettirip kaydettirmediğinize bağlı olarak değişir.

Home API'lerini kullanarak uygulama yayınlamak için Developer Console kaydı gereklidir. Ev API'lerini test etmek ve kullanmak için gerekli değildir.

Developer Console'da kayıtlı olmayan uygulamalar doğrulanmamış durumda olur. Home API'lerinin kullanımını test etmek için aşağıdakiler önerilir:

• Yalnızca OAuth konsolunda test kullanıcısı olarak kayıtlı olan kullanıcılar uygulamaya izin verebilir. Doğrulanmamış bir uygulama için test kullanıcılarının sayısı 100 ile sınırlıdır.

• Doğrulanmamış bir uygulama, Home API'leri için OAuth tarafından desteklenen tüm cihaz türlerindeki cihazlara erişebilir (Developer Console içindeki cihaz türlerinin listesi). Bir yapıdaki tüm cihazlara erişim izni verilir.

Bir uygulama Developer Console kayıtlıysa ve bir veya daha fazla cihaz türüne erişim için onaylanmışsa ve OAuth için marka doğrulaması tamamlanmışsa, doğrulanmış durumda olur. Bir uygulamayı üretimde kullanıma sunmak için bu durum gereklidir:

• Test kullanıcısı sınırları artık geçerli değildir. Herhangi bir kullanıcı uygulamaya izin verebilir.
• Kullanıcı, yalnızca Developer Console içinde onaylanan cihaz türlerine izin verebilir.

OAuth ayarlandığına göre, uygulamanın requestPermissions() çağrısı aşağıdaki iletişim kutularını tetikler:

1. Kullanıcıdan, kullanmak istediği Google Hesabı'nı seçmesi istenir.
2. Kullanıcıdan, uygulamaya erişim izni vermek istediği yapıyı seçmesi istenir.
   1. Doğrulanmamış bir uygulama için Home API'leri tarafından desteklenen tüm cihaz türleri kullanılabilir.
   2. Doğrulanmış bir uygulama için kullanıcı, yalnızca Developer Console içinde onaylanmış cihaz türlerine izin verebilir.
   3. Uygulamanın yönetmek için eriştiği hassas cihaz türlerinde kullanıcı, erişimi cihaz bazında kısıtlayabilir. Örneğin, bir kullanıcının üç kilidi varsa yalnızca bu kilitlerden birine erişim izni verebilir.

İzin verildikten sonra uygulama, Home API'lerini kullanarak yapının durumunu okuyabilir ve yapıda bulunan cihazları kontrol edebilir. Kullanıcı, belirli bir cihaz türü veya hassas cihaz için uygulamaya izin vermezse uygulama, Home API'lerini kullanarak cihaza erişemez, cihazı kontrol edemez veya otomatikleştiremez.

İzinleri değiştir

Farklı bir yapıdaki cihazlara erişim izni vermek için hesap seçici başlatılabilir. Böylece kullanıcı, geçiş yapılacak Google Hesabı'nı ve yapıyı seçebilir. Bu işlem sırasında, daha önce izin verilmiş olsa bile kullanıcıya kullanıcı rızası ekranı tekrar gösterilir.

Bu işlem, requestPermissions() işlevi forceLaunch işareti true olarak ayarlanmış şekilde tekrar çağrılarak yapılabilir:

homeManager.requestPermissions(forceLaunch=true)

Yapı ipuçlarıyla izinleri değiştirme

Yapı ipucu, bir uygulamanın kullanıcının Home API'leri izinlerinde artımlı bir değişiklik isterken belirli bir yapıyı önceden seçmesine veya kullanılabilir yapıların listesini kısıtlamasına olanak tanır. Yetkilendirme isteğine yapı parametreleri iletilerek izin iletişim kutusunun otomatik olarak seçilen yapıya odaklanması sağlanır. Bu sayede kullanıcıların yaşadığı sorunlar azaltılır ve yapılandırma hataları önlenir.

Yapı ipuçları, ConsentScreenOptions veri sınıfı kullanılarak yönetilir. ConsentScreenOptions sınıfı aşağıdaki yapılandırma parametrelerini kabul eder:

• structureId — İzin iletişim kutusunda önceden seçilecek belirli yapı kimliği. Güncellenen yapının yapı özelliklerini kontrol ederek bu değeri elde edebilirsiniz.
• allowedStructureIds: Yapı kimliklerinin listesi. Sağlanırsa izin iletişim kutusu, kullanılabilir yapıları yalnızca bu listedekileri gösterecek şekilde filtreler. Kullanıcının önceden verilmiş bir yapı listesinde kalmasını sağlamak istemediğiniz sürece bu çoğu durumda belirtilmeden bırakılabilir.
• allowStructureChange: Kullanıcının önceden seçilmiş yapıyı değiştirmesine izin verilip verilmediğini belirler. Kullanıcının doğal davranışını desteklemek için çoğu durumda allowedStructureIds ve structureId özelliklerinden en az biri belirtilmişse bunu true olarak ayarlayın.

Bu nesneyi requestPermissions() çağrısında isteğe bağlı bir parametre olarak iletin. forceLaunch işareti true olarak ayarlanmalıdır:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forceLaunch=true, consentOptions)

Kullanıcıya, ConsentScreenOptions nesnesinde belirtilen yapıya göre önceden filtrelenmiş kullanıcı rızası ekranı gösterilir.

Kullanıcının yapı ipuçlarıyla yapılar arasında geçiş yapmasına izin verin

Bir kullanıcının uygulamada birden fazla yapısı varsa ve kullanıcıya mevcut yapıları arasında geçiş yapma olanağı tanırken bir yapıyı önceden seçmek istiyorsanız allowStructureChange işaretiyle yapı değişikliklerini etkinleştirin ve allowedStructureIds içinde yapıların listesini sağlayın:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

İzinleri iptal etme

Kullanıcılar daha önce verilen erişimi iptal edebilir:

1. Google Hesaplarım sayfası > Veriler ve gizlilik > Üçüncü taraf uygulamaları ve hizmetleri üzerinden. Bu işlem, ilk izin verildiğinde verilen OAuth jetonunu ve kullanıcının tüm yüzeylerde (telefonlar) ve yapılarda kullandığı uygulamanın tüm örneklerine erişimi iptal eder.

   Kullanıcı, aşağıdaki URL şemasını kullanarak derin bağlantıyla Üçüncü taraf uygulamaları ve hizmetleri alt sayfasına yönlendirilebilir:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

2. GHA > Ayarlar > Bağlı Uygulamalar sayfasından settings simgesini tıkladığınızda GHA Ayarlar sayfasına yönlendirilirsiniz. Buradan, kullanıcı rızası ekranına benzeyen bir sayfaya yönlendiren Bağlı Uygulamalar kutusunu tıklayın. Kullanıcı bu sayfadan uygulamaya erişimi kaldırabilir. Kullanıcı, uygulamaya hangi cihaz türlerinin veya belirli hassas cihazların erişebileceğini değiştirmek için de aynı sayfayı kullanabilir.

Kullanıcının izin verdiği cihaz türlerini görüntüleme

Google Home ekosisteminde, çoğu cihaz türünde kullanıcılar bu türdeki tüm cihazlar için izinleri tek seferde verebilir. Kilitler, kameralar veya kapı zilleri gibi hassas ya da kısıtlanmış cihaz türleri için kullanıcıların bu cihazlara tek tek izin vermesi gerekir.

Bir kullanıcının hassas veya kısıtlanmış bir cihaz türüne erişim izni verip vermediğini belirlemek için yapı düzeyinde consentedDeviceTypes() işlevini kullanın:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

OkGoogle permissions (OkGoogle izinleri)

okGoogle komutu, cihaz düzeyinde bir komuttur ve yapıda bulunan tüm cihazları otomatik hale getirmek için kullanılabilir. Ancak Home API'leri uygulaması her cihaza erişemeyebilir. Aşağıdaki tabloda, bu gibi durumlarda izinlerin nasıl zorunlu kılındığı açıklanmaktadır.

Kullanıcı tam izinleri iptal ederse

Kullanıcı tam izinleri iptal ederse mevcut tüm otomasyonlar çalışmayı durdurur. Ayrıca, kullanıcı belirli cihazlara erişimi iptal ederse bu cihazlarla ilişkili başlatıcılar, koşullar ve işlemler çalışmayı durdurur.

Uygulama her başlatıldığında izinlerin geçerliliğini koruduğundan emin olun. İzinler iptal edildiyse uygulamada önbelleğe alınan veriler de dahil olmak üzere önceki tüm verilerin kaldırıldığından emin olun.