Permissions API

Sebelum menggunakan Home API, aplikasi harus memiliki izin untuk mengakses perangkat di rumah pengguna, yang disebut dalam API sebagai struktur.

Home API menggunakan OAuth 2.0 untuk memberikan akses ke perangkat dalam struktur. OAuth memungkinkan pengguna memberikan izin ke aplikasi atau layanan tanpa harus mengekspos kredensial login mereka. Dengan Permissions API, pengguna dapat, menggunakan Akun Google mereka, memberikan akses ke aplikasi Home API ke perangkat di rumah mereka.

Penggunaan Permissions API melibatkan sejumlah langkah di aplikasi Anda, Google Cloud, dan Google Home Developer Console:

1. Menyiapkan OAuth di Google Cloud
   1. Menandatangani aplikasi
   2. Menyiapkan layar izin OAuth
   3. Mendaftarkan aplikasi dan membuat kredensial
2. Mengintegrasikan Permissions API
   1. Memeriksa izin
   2. Meminta izin
3. Memberikan izin
   1. Ubah izin
   2. Mencabut izin

Menyiapkan OAuth di Google Cloud

Jika sudah memiliki klien OAuth terverifikasi, Anda dapat menggunakan klien tersebut tanpa menyiapkan klien baru. Untuk informasi selengkapnya, lihat Jika Anda sudah memiliki klien OAuth.

Menandatangani aplikasi

1. Buat kunci OAuth dengan menjalankan aplikasi di Android Studio. Saat Anda menjalankan atau men-debug aplikasi di Android Studio, aplikasi tersebut akan otomatis menghasilkan kunci OAuth yang ditujukan untuk pengembangan dan proses debug. Lihat Android Studio: Menandatangani build debug untuk mengetahui penjelasan lengkapnya.

   Hubungkan perangkat seluler ke komputer lokal. Android Studio akan mencantumkan perangkat yang terhubung menurut nomor model. Pilih perangkat Anda dari daftar, lalu klik Run project. Tindakan ini akan mem-build dan menginstal aplikasi contoh di perangkat seluler Anda.

   Untuk petunjuk yang lebih mendetail, lihat Menjalankan aplikasi di perangkat hardware di situs Android Developers.

   Sekarang hentikan aplikasi yang sedang berjalan.

2. Dapatkan sidik jari SHA-1 sertifikat OAuth dengan mengikuti petunjuk yang dijelaskan dalam Menyiapkan OAuth 2.0 / Aplikasi native/Android di situs Bantuan Konsol Google Cloud.

Menyiapkan layar izin OAuth

1. Di konsol Google Cloud, buka dasbor pemilih project dan pilih project yang ingin Anda gunakan untuk membuat kredensial OAuth.
2. Buka halaman APIs and Services, lalu klik Credentials di menu navigasi.

3. Jika Anda belum mengonfigurasi layar izin untuk project Google Cloud ini, tombol Konfigurasi layar izin akan muncul. Dalam hal ini, konfigurasi layar izin Anda menggunakan prosedur berikut. Jika tidak, lanjutkan ke bagian berikutnya.

   1. Klik Konfigurasi layar izin. Halaman OAuth consent screen akan ditampilkan.
   2. Bergantung pada kasus penggunaan Anda, pilih Internal atau External, lalu klik Create. Panel OAuth consent screen akan ditampilkan.
   3. Masukkan informasi di halaman Informasi aplikasi sesuai dengan petunjuk di layar, lalu klik Simpan dan lanjutkan. Panel Scopes akan ditampilkan.
   4. Anda tidak perlu menambahkan cakupan apa pun, jadi klik Save and continue. Panel Test users akan ditampilkan.
   5. Jika Anda ingin menambahkan pengguna untuk menguji akses ke aplikasi, klik Tambahkan pengguna. Panel Tambahkan pengguna akan ditampilkan. Pengguna pengujian memiliki hak istimewa untuk memberikan izin di aplikasi Anda.
   6. Di kolom kosong, tambahkan satu atau beberapa alamat email Akun Google, lalu klik Tambahkan.
   7. Klik Simpan dan lanjutkan. Panel Ringkasan akan ditampilkan.
   8. Tinjau informasi layar izin OAuth Anda, lalu klik Kembali ke dasbor.

Lihat Menyiapkan layar izin OAuth di situs Bantuan Konsol Google Cloud untuk mengetahui detail selengkapnya.

Mendaftarkan aplikasi dan membuat kredensial

Untuk mendaftarkan aplikasi ke OAuth 2.0 dan membuat kredensial OAuth, ikuti petunjuk yang diberikan di Menyiapkan OAuth 2.0. Anda harus menunjukkan jenis aplikasi, yaitu aplikasi native/Android.

Tambahkan sidik jari SHA-1 yang Anda dapatkan dari menandatangani aplikasi ke klien OAuth yang Anda siapkan di konsol Google Cloud dengan mengikuti petunjuk di Menyiapkan aplikasi OAuth 2.0 / Native di situs Bantuan Google Cloud Console.

Dengan perangkat seluler yang terhubung ke mesin lokal, pilih perangkat dari daftar, lalu klik Run project lagi untuk menjalankannya. Untuk petunjuk yang lebih mendetail, lihat Menjalankan aplikasi di perangkat hardware di situs Android Developers.

Mengintegrasikan Permissions API

Pengguna harus memberikan izin ke aplikasi Anda untuk mengakses perangkat dalam struktur tertentu. Untuk memulai, pastikan Anda telah mengikuti langkah-langkah dalam melakukan inisialisasi Home API. Instance homeManager dari langkah tersebut digunakan dalam semua contoh Izin di sini.

Pertama, daftarkan ActivityResultCaller dengan SDK. Misalnya, berikut cara aplikasi contoh menanganinya:

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

Memeriksa izin

Sebelum meminta izin, sebaiknya Anda memeriksa apakah pengguna aplikasi telah memberikan izin. Untuk melakukannya, panggil metode hasPermissions() dari instance Home untuk mendapatkan Flow dari nilai PermissionsState:

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")
  }
}

Jika pemeriksaan menampilkan PermissionsState dari NOT_GRANTED atau PERMISSIONS_STATE_UNAVAILABLE, Anda harus meminta izin. Jika pemeriksaan menampilkan PermissionsState dari GRANTED, tetapi panggilan berikutnya ke structures() tidak menampilkan struktur, pengguna telah mencabut akses ke aplikasi melalui halaman setelan Google Home app (GHA), dan Anda harus meminta izin. Jika tidak, pengguna seharusnya sudah memiliki akses.

Meminta izin

Izin harus diberikan ke aplikasi Anda untuk mengakses struktur dan perangkat dalam struktur tertentu.

Jika pengguna belum memberikan izin, gunakan metode requestPermissions() dari instance Home untuk meluncurkan UI Izin dan memproses hasilnya:

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}")
      }
    }
  }
}

Agar UI Izin diluncurkan dengan benar, Anda harus sudah menyiapkan OAuth untuk aplikasi Anda.

Berikan izin

Sekarang Anda dapat menjalankan aplikasi dan meminta pengguna memberikan izin. Jenis pengguna yang dapat memberikan izin, dan jenis perangkat yang tersedia untuk memberikan izin, akan berbeda-beda bergantung pada apakah Anda telah mendaftarkan aplikasi di Developer Console.

Pendaftaran Developer Console diperlukan untuk memublikasikan aplikasi menggunakan Home API. Anda tidak perlu menguji dan menggunakan Home API. Untuk mendapatkan akses ke fitur pendaftaran konsol, hubungi Technical Account Manager (TAM) Google Anda.

Jika tidak terdaftar di Developer Console, aplikasi akan berada dalam status tidak diverifikasi. Hal ini direkomendasikan untuk menguji penggunaan Home API:

• Hanya pengguna yang terdaftar sebagai pengguna pengujian di konsol OAuth yang dapat memberikan izin untuk aplikasi. Ada batas 100 pengguna pengujian untuk aplikasi yang tidak terverifikasi.

• Aplikasi yang tidak terverifikasi akan memiliki akses ke perangkat dari jenis perangkat apa pun yang didukung oleh OAuth untuk Home API (daftar jenis perangkat di Developer Console). Semua perangkat dalam struktur akan diberikan.

Jika aplikasi terdaftar di Developer Console dan telah disetujui untuk mengakses satu atau beberapa jenis perangkat, dan verifikasi merek telah selesai untuk OAuth, aplikasi akan berada dalam status terverifikasi. Status ini diperlukan untuk meluncurkan aplikasi ke produksi:

• Batas pengguna pengujian tidak berlaku lagi. Setiap pengguna dapat memberikan izin ke aplikasi.
• Pengguna hanya dapat memberikan izin ke jenis perangkat yang disetujui di Developer Console.

Setelah OAuth disiapkan, panggilan aplikasi ke requestPermissions() akan memicu dialog berikut:

1. Pengguna akan diminta memilih Akun Google yang ingin digunakan.
2. Pengguna diminta untuk memilih struktur yang ingin diberi akses oleh aplikasi.
   1. Untuk aplikasi yang tidak terverifikasi, semua jenis perangkat yang didukung oleh Home API tersedia untuk aplikasi.
   2. Untuk aplikasi terverifikasi, pengguna hanya dapat memberikan izin ke jenis perangkat yang telah disetujui di Developer Console.
   3. Untuk jenis perangkat sensitif yang dapat dikelola oleh aplikasi, pengguna dapat membatasi akses berdasarkan per perangkat. Misalnya, jika pengguna memiliki tiga kunci, mereka hanya dapat memberikan akses ke salah satu kunci tersebut.

Setelah izin diberikan, aplikasi dapat menggunakan Home API untuk membaca status dan mengontrol perangkat dalam struktur. Jika pengguna tidak memberikan izin ke aplikasi untuk jenis perangkat tertentu atau perangkat sensitif, aplikasi tidak akan dapat menggunakan Home API untuk mengakses, mengontrol, atau mengotomatiskan perangkat tersebut.

Ubah izin

Untuk memberikan izin guna mengakses perangkat dalam struktur yang berbeda, pemilih akun dapat diluncurkan agar pengguna dapat memilih Akun Google dan struktur yang akan digunakan. Selama proses ini, pengguna akan melihat layar izin lagi, meskipun izin telah diberikan sebelumnya.

Tindakan ini dapat dilakukan dengan memanggil requestPermissions() lagi dengan flag forceLaunch ditetapkan ke true:

homeManager.requestPermissions(forceLaunch=true)

Mencabut izin

Pengguna dapat mencabut akses yang sebelumnya diberikan:

1. Melalui halaman Google MyAccounts > Data & privasi > Aplikasi & layanan pihak ketiga. Tindakan ini akan mencabut token OAuth yang dikeluarkan saat izin awal diberikan, dan akan mencabut akses ke instance aplikasi apa pun yang digunakan pengguna di semua platform (ponsel) dan struktur.

2. Melalui halaman GHA > Setelan > Aplikasi Tertaut. Mengklik settings di GHA akan mengarahkan Anda ke halaman Setelan. Dari sana, klik kartu Aplikasi Tertaut yang akan mengarahkan Anda ke halaman yang terlihat mirip dengan layar izin. Dari halaman ini, pengguna dapat menghapus akses ke aplikasi. Pengguna dapat menggunakan halaman yang sama ini untuk mengubah jenis perangkat atau perangkat sensitif tertentu yang dapat diakses oleh aplikasi.

3. Melalui halaman Aplikasi Tertaut langsung di web.

Jika Anda sudah memiliki klien OAuth

Jika sudah memiliki klien OAuth terverifikasi untuk aplikasi yang dipublikasikan, Anda dapat menggunakan klien OAuth yang ada untuk menguji Home API.

Pendaftaran Developer Console tidak diperlukan untuk menguji dan menggunakan Home API. Namun, Anda tetap memerlukan pendaftaran Developer Console yang disetujui untuk memublikasikan aplikasi, meskipun Anda memiliki klien OAuth terverifikasi dari integrasi lain.

Pertimbangan berikut berlaku:

• Ada batas 100 pengguna saat menggunakan klien OAuth yang sudah ada. Untuk informasi tentang cara menambahkan pengguna pengujian, lihat Menyiapkan layar izin OAuth. Terlepas dari verifikasi OAuth, ada batas 100 pengguna yang dapat memberikan izin ke aplikasi Anda yang diberlakukan oleh Home API. Batasan ini dicabut setelah pendaftaran Developer Console selesai.

• Developer Console pendaftaran harus dikirim untuk disetujui saat Anda siap membatasi pemberian jenis perangkat melalui OAuth sebagai persiapan untuk mengupdate aplikasi dengan Home API.

Untuk aplikasi Google Cloud yang masih menunggu verifikasi OAuth, pengguna tidak dapat menyelesaikan alur OAuth hingga verifikasi selesai. Upaya untuk memberikan izin akan gagal dengan error berikut:

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

Izin OkGoogle

Perintah okGoogle adalah perintah tingkat struktur dan dapat digunakan untuk mengotomatiskan perangkat apa pun dalam struktur. Namun, aplikasi Home API mungkin tidak memiliki akses ke setiap perangkat. Tabel berikut menjelaskan cara izin diterapkan dalam kasus tersebut.