Permissions API di Android

Sebelum menggunakan salah satu Home API untuk Android, aplikasi harus memiliki izin untuk mengakses perangkat di rumah pengguna, yang disebut dalam API sebagai struktur. Dengan Permissions API, pengguna dapat, menggunakan Akun Google mereka, memberikan akses aplikasi Home API ke perangkat di rumah mereka.

Mengintegrasikan Permissions API

Sebelum melanjutkan, pastikan Anda telah mengikuti Menginisialisasi rumah di Android. 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 mengakses struktur. Untuk melakukannya, panggil metode hasPermissions() instance Beranda untuk mendapatkan Flow dari nilai PermissionsState:

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

Jika pemeriksaan menampilkan PermissionsState NOT_GRANTED atau PERMISSIONS_STATE_UNAVAILABLE, berarti pengguna atau aplikasi tidak memiliki akses ke struktur. Jika pemeriksaan menampilkan PermissionsState GRANTED, tetapi panggilan berikutnya ke structures() tidak menampilkan struktur, maka pengguna telah mencabut akses ke aplikasi melalui halaman setelan Google Home app (GHA), atau pengguna tidak memiliki akses yang diperlukan.

Meminta izin

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

Jika pengguna belum memberikan izin, gunakan metode requestPermissions() 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 Google Home Developer Console.

Pendaftaran Developer Console diperlukan untuk memublikasikan aplikasi menggunakan Home API. Anda tidak perlu menguji dan menggunakan Home API.

Jika aplikasi tidak terdaftar di Developer Console, aplikasi akan berada dalam status tidak terverifikasi. Direkomendasikan untuk menguji penggunaan API Home:

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

• Aplikasi yang belum diverifikasi 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 diberi akses.

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

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

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

1. Pengguna akan diminta memilih Akun Google yang ingin mereka gunakan.
2. Pengguna diminta untuk memilih struktur yang ingin mereka beri akses 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 akses pengelolaannya dimiliki aplikasi, pengguna dapat membatasi akses berdasarkan per perangkat. Misalnya, jika pengguna memiliki tiga kunci, dia hanya dapat memberikan akses ke salah satu kunci tersebut.

Setelah izin diberikan, aplikasi dapat menggunakan API Home 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 akses ke perangkat dalam struktur yang berbeda, pemilih akun dapat diluncurkan untuk memungkinkan pengguna memilih Akun Google dan struktur yang akan digunakan. Selama proses ini, pengguna akan melihat layar izin lagi, meskipun izin telah diberikan sebelumnya.

Hal ini dapat dilakukan dengan memanggil requestPermissions() lagi dengan tanda forceLaunch yang ditetapkan ke true:

homeManager.requestPermissions(forceLaunch=true)

Mencabut izin

Pengguna dapat mencabut akses yang diberikan sebelumnya:

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

   Pengguna dapat diarahkan dengan deep link ke sub-halaman Aplikasi & layanan pihak ketiga menggunakan skema URL berikut:

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

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 membawa 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.

Izin OkGoogle

Perintah okGoogle adalah perintah tingkat perangkat 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.