İzinler API'si

Home API'lerinden herhangi birini kullanmadan önce uygulamanın, kullanıcının evinde bulunan cihazlara (API'de yapı olarak adlandırılır) erişme izni olmalıdır.

Home API'leri, yapıdaki cihazlara erişim izni vermek için OAuth 2.0'ı kullanır. OAuth, kullanıcıların giriş kimlik bilgilerini göstermek zorunda kalmadan bir uygulamaya veya hizmete izin vermesine olanak tanır. Kullanıcı, Permissions API ile Google Hesabını kullanarak Home API'leri kullanan uygulamalara evlerindeki cihazlara erişim izni verebilir.

Permissions API'yi kullanmak için uygulamanızda, Google Cloud'da ve Google Home Developer Console'te bir dizi adım uygulamanız gerekir:

1. Google Cloud'da OAuth'u ayarlama
   1. Uygulamayı imzalama
   2. OAuth izin ekranını ayarlama
   3. Uygulamayı kaydetme ve kimlik bilgileri oluşturma
2. Permissions API'yi entegre etme
   1. İzinleri kontrol etme
   2. İzin isteme
3. İzin verme
   1. İzinleri değiştir
   2. İzinleri iptal etme

Google Cloud'da OAuth'u ayarlama

Doğrulanmış bir OAuth istemciniz varsa yeni bir istemci oluşturmadan bu istemciyi kullanabilirsiniz. Daha fazla bilgi için Mevcut bir OAuth istemciniz varsa başlıklı makaleyi inceleyin.

Uygulamayı imzalama

1. Uygulamayı Android Studio'te çalıştırarak bir OAuth anahtarı oluşturun. Android Studio'te bir uygulamayı çalıştırdığınızda veya uygulamada hata ayıklama yaptığınızda, geliştirme ve hata ayıklama için otomatik olarak bir OAuth anahtarı oluşturulur. Tam açıklama için Android Studio: Hata ayıklama derlemenizi imzalama başlıklı makaleyi inceleyin.

   Mobil cihazınızı yerel makinenize bağlayın. Android Studio, bağlı cihazlarınızı model numarasına göre listeler. Listeden cihazınızı seçip Projeyi çalıştır'ı tıklayın. Bu işlem, örnek uygulamayı oluşturup mobil cihazınıza yükler.

   Daha ayrıntılı talimatlar için Android Developers sitesinde Donanım cihazında uygulama çalıştırma başlıklı makaleyi inceleyin.

   Ardından, çalışan uygulamayı durdurun.

2. Google Cloud Console Yardım sitesindeki OAuth 2.0'ı ayarlama / Yerel uygulamalar / Android bölümünde ayrıntılı olarak açıklanan talimatları uygulayarak OAuth sertifikasının SHA-1 parmak izini alın.

OAuth izin ekranını ayarlama

1. Google Cloud Console'da proje seçici kontrol paneline gidin ve OAuth kimlik bilgileri oluşturmak için kullanmak istediğiniz projeyi seçin.
2. API'ler ve Hizmetler sayfasına gidin ve gezinme menüsünde Kimlik bilgileri'ni tıklayın.

3. Bu Google Cloud projesi için izin ekranınızı henüz yapılandırmadıysanız İzin ekranını yapılandır düğmesi görünür. Bu durumda, izin ekranınızı aşağıdaki prosedürü kullanarak yapılandırın. Aksi takdirde bir sonraki bölüme geçin.

   1. İzin ekranını yapılandır'ı tıklayın. OAuth kullanıcı rızası ekranı sayfası gösterilir.
   2. Kullanım alanınıza bağlı olarak Dahili veya Harici'yi seçin ve ardından Oluştur'u tıklayın. OAuth izin ekranı bölmesi gösterilir.
   3. Uygulama bilgileri sayfasında ekrandaki talimatlara göre bilgileri girin ve Kaydet ve devam et'i tıklayın. Kapsamlar bölmesi görüntülenir.
   4. Herhangi bir kapsam eklemeniz gerekmez. Kaydet ve devam et'i tıklayın. Test kullanıcıları bölmesi gösterilir.
   5. Uygulamanıza erişimi test etmek için kullanıcı eklemek istiyorsanız Kullanıcı ekle'yi tıklayın. Kullanıcı ekle bölmesi gösterilir. Test kullanıcıları, uygulamanızda izin verme ayrıcalığına sahiptir.
   6. Boş alana bir veya daha fazla Google Hesabı e-posta adresi ekleyin ve ardından Ekle'yi tıklayın.
   7. Kaydet ve devam et'i tıklayın. Özet bölmesi gösterilir.
   8. OAuth izin ekranı bilgilerinizi inceleyin ve ardından Kontrol paneline dön'ü tıklayın.

Ayrıntılı bilgi için Google Cloud Console Yardım sitesindeki OAuth kullanıcı rızası ekranınızı ayarlama başlıklı makaleyi inceleyin.

Uygulamayı kaydetme ve kimlik bilgileri oluşturma

Uygulamayı OAuth 2.0'a kaydettirmek ve OAuth kimlik bilgileri oluşturmak için OAuth 2.0 kurulumu başlıklı makalede verilen talimatları uygulayın. Uygulama türünü (yerel/Android uygulaması) belirtmeniz gerekir.

Uygulamayı imzalarken aldığınız SHA-1 parmak izini, Google Cloud Console Yardım sitesindeki OAuth 2.0 / Yerel uygulamaları ayarlama başlıklı makaledeki talimatları uygulayarak Google Cloud Console'da oluşturduğunuz OAuth istemciye ekleyin.

Mobil cihazınız yerel makinenize bağlıyken listeden cihazınızı seçin ve ardından Projeyi çalıştır'ı tekrar tıklayarak projeyi çalıştırın. Daha ayrıntılı talimatlar için Android Developers sitesinde Donanım cihazında uygulama çalıştırma başlıklı makaleyi inceleyin.

Permissions API'yi entegre etme

Kullanıcılar, belirli bir yapıdaki cihazlara erişmek için uygulamanıza izin vermelidir. Başlamadan önce Home API'lerini başlatma bölümünü uyguladığınızdan emin olun. Bu adımdaki homeManager örneği, buradaki tüm izin örneklerinde kullanılır.

Öncelikle SDK'ya 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 izin verip vermediğini kontrol etmenizi öneririz. Bunun için, Home örneğinin hasPermissions() yöntemini çağırarak PermissionsState değerinden oluşan bir Flow elde edin:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      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")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Kontrol, NOT_GRANTED veya PERMISSIONS_STATE_UNAVAILABLE değerinde bir PermissionsState döndürüyorsa izin isteğinde bulunmanız gerekir. Kontrol, GRANTED değerinde bir PermissionsState döndürür ancak structures() için yapılan sonraki bir çağrıda yapı döndürülmezse kullanıcı, Google Home app (GHA) ayarlar sayfası üzerinden uygulamaya erişimi iptal etmiş demektir ve izin isteğinde bulunmanız gerekir. Aksi takdirde, kullanıcının zaten erişimi olmalıdır.

İzin isteme

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

Kullanıcı henüz izin vermediyse İzinler kullanıcı arayüzünü başlatmak ve sonucu işlemek için Ana Sayfa ö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ız için OAuth'u ayarlamanız gerekir.

İzin verin

Artık uygulamanızı çalıştırabilir ve kullanıcıların izin vermesini sağlayabilirsiniz. İzin verebilecek kullanıcı türleri ve izin verilebilen cihaz türleri, uygulamanızı Developer Console'e kaydettirmiş olmanıza bağlı olarak farklılık gösterir.

Home API'lerini kullanarak uygulama yayınlamak için Developer Console kaydı gereklidir. Home API'lerini test etmek ve kullanmak gerekli değildir. Konsol kaydı özelliğine erişmek için Google Technical Account Manager (TAM) ile iletişime geçin.

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

• Uygulama için izin verebilecek kullanıcılar yalnızca OAuth konsolunda test kullanıcısı olarak kayıtlı kullanıcılardır. Doğrulanmamış uygulamalar 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ürlerine (Developer Console'teki cihaz türlerinin listesi) erişebilir. Bir yapıdaki tüm cihazlara erişim izni verilir.

Developer Console 'e kayıtlı bir uygulama, 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ış durumunda olur. Bir uygulamayı üretime sunmak için bu durum gereklidir:

• Test kullanıcısı sınırları artık geçerli değildir. Tüm kullanıcılar uygulamaya izin verebilir.
• Kullanıcı yalnızca Developer Console'te onaylanan cihaz türlerine izin verebilir.

OAuth ayarlandıktan sonra uygulamanın requestPermissions()'e yaptığı çağrı 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, 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'te onaylanmış cihaz türlerine izin verebilir.
   3. Uygulamanın yönetme erişimi olan hassas cihaz türleri için kullanıcı, erişimi cihaz başına kısıtlayabilir. Örneğin, üç kilidi olan bir kullanıcı bu kilitlerden yalnızca 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ı, uygulamaya belirli bir cihaz türü veya hassas cihaz için izin vermezse uygulama, cihaza erişmek, cihazı kontrol etmek veya otomatikleştirmek için Home API'lerini kullanamaz.

İzinleri değiştir

Farklı bir yapıdaki cihazlara erişim izni vermek için hesap seçiciyi başlatarak kullanıcının geçiş yapacağı Google Hesabı'nı ve yapıyı seçmesine izin verilebilir. Bu işlem sırasında, daha önce izin verilmiş olsa bile kullanıcıya izin ekranı tekrar gösterilir.

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

homeManager.requestPermissions(forceLaunch=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'ni kullanarak. 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ığı uygulama örneğine erişimi iptal eder.

2. GHA > Ayarlar > Bağlı Uygulamalar sayfasından GHA bölümündeki settings simgesini tıkladığınızda Ayarlar sayfasına yönlendirilirsiniz. Buradan Bağlı Uygulamalar kartını tıklayın. Bu kart sizi izin ekranına benzer bir sayfaya yönlendirir. Kullanıcı bu sayfadan uygulamaya erişimi kaldırabilir. Aynı sayfayı kullanarak uygulamanın hangi cihaz türlerine veya belirli hassas cihazlara erişebileceğini değiştirebilir.

3. Doğrudan web'deki Bağlı Uygulamalar sayfası üzerinden.

Mevcut bir OAuth istemciniz varsa

Yayınlanmış bir uygulama için doğrulanmış bir OAuth istemciniz varsa Home API'leri test etmek için mevcut OAuth istemcinizi kullanabilirsiniz.

Home API'leri test etmek ve kullanmak için Developer Console kaydı gerekli değildir. Ancak, başka bir entegrasyondan doğrulanmış bir OAuth istemciniz olsa bile uygulamanızı yayınlamak için onaylanmış bir Developer Console kaydına ihtiyacınız vardır.

Aşağıdaki noktalar dikkate alınmalıdır:

• Mevcut bir OAuth istemcisi kullanırken 100 kullanıcı sınırı vardır. Test kullanıcıları ekleme hakkında bilgi edinmek için OAuth izin ekranını ayarlama başlıklı makaleyi inceleyin. OAuth doğrulamasından bağımsız olarak, uygulamanıza izin verebilecek 100 kullanıcıyla sınırlı bir Home API'si sınırı vardır. Bu sınırlama, Developer Console kaydı tamamlandıktan sonra kaldırılır.

• Developer Console registration , uygulamanızı Home API'leriyle güncellemeye hazırlanırken OAuth aracılığıyla cihaz türü izinlerini kısıtlamaya hazır olduğunuzda onaya gönderilmelidir.

OAuth doğrulaması beklemede olan Google Cloud uygulamaları için kullanıcılar, doğrulama tamamlanana kadar OAuth akışını tamamlayamaz. İzin verme girişimleri aşağıdaki hatayla başarısız olur:

Access blocked: <Project Name> has not completed the Google verification process.

OkGoogle izinleri

okGoogle komutu, yapı 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 tür durumlarda izinlerin nasıl uygulandığı açıklanmaktadır.