Permissions API

Sebelum menggunakan Home API, 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 ke aplikasi Home API ke perangkat di rumah mereka.

Mengintegrasikan Permissions API

Sebelum melanjutkan, pastikan Anda telah mengikuti Melakukan inisialisasi rumah. 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 Google Home Developer Console.

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

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.

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.