Android'deki Permissions API

Android için Home API'lerini kullanmadan önce uygulamanın, kullanıcının evindeki cihazlara erişim izni olmalıdır. Bu izin, API'de yapı olarak adlandırılır. Kullanıcı, Permissions API ile 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 bir yapı oluşturmasına ve henüz ayarlanmamışsa açık adresini atamasına olanak tanır.

Permissions API'yi entegre etme

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 Permissions ö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, uygulama kullanıcısının yapıya erişim izni verip vermediğini kontrol etmenizi öneririz. Bunun için Home örneğinin hasPermissions() yöntemini çağırarak PermissionsState değerlerinin Flow değerini alı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, NOT_GRANTED veya PERMISSIONS_STATE_UNAVAILABLE değerinde bir PermissionsState döndürürse kullanıcının ya da uygulamanın yapıya erişimi yok demektir. Kontrol sonucunda GRANTED değerine sahip bir PermissionsState döndürülür ancak sonraki structures() çağrısında yapı döndürülmezse kullanıcı, GHA ayarlar sayfasından uygulamanın erişimini iptal etmiştir veya gerekli erişime sahip değildir.

İzin iste

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

Kullanıcı henüz izin vermediyse izinler 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ılması için uygulamanızda OAuth'u ayarlamış olmanız gerekir.

İzin rızası kullanıcı arayüzü, HomeClient.setLocale() ile yapılandırılan yerel ayarda oluşturulur veya ayarlanmamışsa varsayılan olarak uygulama ya da cihaz yerel ayarına ayarlanır. Kullanıcı rızası ekranını belirli bir dilde görüntülemek için requestPermissions() yöntemini çağırmadan önce HomeClient örneğinizde setLocale() yöntemini çağırın. Daha fazla bilgi için Uygulama yerel ayarını yapılandırma başlıklı makaleyi inceleyin.

İzin verin

Artık uygulamanızı çalıştırabilir ve bir kullanıcının izin vermesini sağlayabilirsiniz. İzin verebilecek kullanıcı türleri ve izin verilebilecek cihaz türleri, uygulamanızı Google Home Developer Console platformuna kaydedip kaydetmediğinize bağlı olarak farklılık gösterir.

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

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

• Yalnızca OAuth konsolunda test kullanıcısı olarak kayıtlı kullanıcılar uygulama için izin verebilir. Doğrulanmamış bir uygulama için 100 test kullanıcısı sınırı vardı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'da kayıtlıysa ve bir veya daha fazla cihaz türüne erişim için onaylandıysa ve OAuth için marka doğrulaması tamamlandıysa doğrulanmış durumda olur. Bir uygulamayı üretim aşamasına geçirmek 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, uygulamanın erişmesine izin vermek istediği yapıyı seçmesi istenir.
   1. Doğrulanmamış bir uygulama, Home API'leri tarafından desteklenen tüm cihaz türlerini kullanabilir.
   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önetme erişimine sahip olduğu hassas cihaz türleri için kullanıcı, erişimi cihaz bazında kısıtlayabilir. Örneğin, üç kilidi olan bir kullanıcı yalnızca bu kilitlerden birine erişim izni verebilir.

İzin verildikten sonra uygulama, yapıdaki cihazların durumunu okumak ve kontrol etmek için Home API'lerini kullanabilir. Kullanıcı, belirli bir cihaz türü veya hassas cihaz için uygulamaya izin vermezse uygulama, Home API'lerini kullanarak bu 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ılarak kullanıcının geçiş yapacağı Google Hesabı'nı ve yapıyı seçmesi sağlanabilir. Bu işlem sırasında, daha önce izin verilmiş olsa bile kullanıcıya kullanıcı rızası ekranı tekrar gösterilir.

Bunun için requestPermissions() yöntemini forcePermissionFlow parametresi ForcePermissionFlow.FORCE_LAUNCH olarak ayarlanmış şekilde tekrar çağırabilirsiniz:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Yapı ipucu verme ile izinleri değiştirme

Yapı ipucu verme, bir uygulamanın kullanıcının Home API'leri izinlerinde artımlı bir değişiklik talep ederken belirli bir yapıyı önceden seçmesine veya mevcut yapıların listesini kısıtlamasına olanak tanır. Yapı parametrelerini yetkilendirme isteğine ileterek izinler iletişim kutusu otomatik olarak seçilen yapıya odaklanır. Bu sayede kullanıcıların yaşadığı zorluklar azalır ve yapılandırma hataları önlenir.

Yapı ipucu verme, 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. Bu bilgiyi, güncellenen yapının yapı özelliklerini kontrol ederek edinebilirsiniz.
• allowedStructureIds: Yapı kimliklerinin listesi. Sağlanırsa izin iletişim kutusu, mevcut yapıları yalnızca bu listedekileri gösterecek şekilde filtreler. Kullanıcının önceden izin verilen bir yapı listesinde kalmasını sağlamak istemediğiniz sürece bu alan çoğu durumda boş bırakılabilir.
• allowStructureChange: Kullanıcının önceden seçilmiş yapıyı değiştirmesine izin verilip verilmediğini belirler. Kullanıcı için doğal davranışı desteklemek amacıyla çoğu durumda allowedStructureIds ve structureId özelliklerinden en az biri belirtilmişse bu özelliği true olarak ayarlayın.

Bu nesneyi, requestPermissions() çağrısında isteğe bağlı bir parametre olarak iletin ve forcePermissionFlow değerini ForcePermissionFlow.FORCE_LAUNCH olarak ayarlayın:

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(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

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

Kullanıcının yapı ipucu verme özelliğiyle yapılar arasında geçiş yapmasına izin verme

Bir kullanıcının uygulamada birden fazla yapısı varsa ve mevcut yapıları arasında geçiş yapmasına izin verirken birini ö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 Hesabı ayarları > Veriler ve gizlilik > Üçüncü taraf uygulamaları ve hizmetleri üzerinden. Bu işlem, ilk izin verildiğinde verilen OAuth jetonunu iptal eder ve kullanıcının tüm platformlarda (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. GHA uygulamasında settings simgesini tıkladığınızda Ayarlar sayfasına yönlendirilirsiniz. Burada, Bağlı Uygulamalar kartını tıklayın. Bu kart sizi kullanıcı rızası ekranına benzer bir sayfaya yönlendirir. Kullanıcı bu sayfadan uygulamanın erişimini kaldırabilir. Kullanıcı, uygulamanın erişebileceği cihaz türlerini veya belirli hassas cihazları değiştirmek için de bu sayfayı kullanabilir.

Kullanıcı verilerini silme ve dışa aktarma

Kullanıcı Google Hesabı'nı sildiğinde veya bir yapıdan ayrıldığında platform, arka uç veri silme işlemini otomatik olarak yönetir:

• Silinen kullanıcı bir yapının tek sahibiyse platform, yapıyı ve cihaz ilişkilendirmelerini siler.
• Paylaşılan bir yapıda başka sahipler varsa yapı ve paylaşılan cihazları, kalan üyeler için kullanılabilir durumda kalır. Platform, ayrılan kullanıcının üyeliğini kaldırır ve yalnızca bu kullanıcının kimlik bilgileriyle bağlanmış tüm üçüncü taraf Cloud-to-cloud cihazlarının bağlantısını kaldırır.
• Hesap silme işlemi, kullanıcının yapı verilerini ve uygulama izinlerini hemen ve kalıcı olarak kaldırır. Kullanıcı daha sonra Google Hesabı'nı kurtarsa bile yapıları ve izinleri geri yüklenmez.

Home API'leri, kullanıcıların Google Hesabı verilerini dışa aktarmak veya silmek için uç noktalar sağlamaz. Google Hesabı olan kullanıcıları, Google Home verilerini dışa aktarmak için Google Paket Servisi'ne, hesap silme işlemlerini yönetmek için ise Google Hesabı ayarlarına yönlendirin.

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

Google Home ekosisteminde kullanıcılar, çoğu cihaz türü için o türdeki tüm cihazlara aynı anda izin verebilir. Kilit, kamera veya kapı zili gibi hassas ya da kısıtlanmış cihaz türleri için kullanıcıların her birine ayrı ayrı 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üzeyindeki 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 izinleri

okGoogle komutu, cihaz düzeyinde bir komuttur ve yapıdaki herhangi bir cihazı otomatikleştirmek için kullanılabilir. Ancak Home API'leri uygulamaları her cihaza erişemeyebilir. Aşağıdaki tabloda, bu gibi durumlarda izinlerin nasıl uygulandığı açıklanmaktadır.

Kullanıcı tam izinleri iptal ederse ne yapılmalı?

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 hâlâ geçerli olup olmadığını kontrol edin. İptal edilmişse uygulamada önbelleğe alınmış veriler de dahil olmak üzere önceki tüm verilerin kaldırıldığından emin olun.

Yapı erişimi iptal edildiğinde bulut arka ucunuza bir StructureAccessRevokedEvent gönderilir. Uçtan uca iş ortağı bulutu ve mobil uygulama iptal iş akışı için İzinleri yapılandırma bölümüne bakın.