Permissions API di Android

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

Alur izin memungkinkan pengguna membuat struktur dan menetapkan alamat jalannya jika belum disiapkan, tanpa harus menggunakan Google Home app (GHA).

Mengintegrasikan Permissions API

Sebelum melanjutkan, pastikan Anda telah mengikuti Melakukan inisialisasi 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 periksa apakah pengguna aplikasi telah memberikan izin untuk mengakses struktur. Untuk melakukannya, panggil metode hasPermissions() instance Home untuk mendapatkan Flow 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 dari NOT_GRANTED atau PERMISSIONS_STATE_UNAVAILABLE, artinya pengguna atau aplikasi tidak memiliki akses ke struktur. Jika pemeriksaan menampilkan PermissionsState GRANTED, tetapi panggilan berikutnya ke structures() tidak menampilkan struktur, berarti pengguna telah mencabut akses ke aplikasi melalui halaman setelan 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 dapat diluncurkan dengan benar, Anda harus sudah menyiapkan OAuth untuk aplikasi Anda.

UI izin Izin dirender di lokalitas yang dikonfigurasi dengan HomeClient.setLocale(), atau ditetapkan secara default ke lokalitas aplikasi atau perangkat jika tidak ditetapkan. Untuk menampilkan layar izin dalam bahasa tertentu, panggil setLocale() di instance HomeClient sebelum memanggil requestPermissions(). Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi lokalitas aplikasi.

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 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 menggunakannya untuk menguji dan menggunakan Home API.

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

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

• Aplikasi yang tidak 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 diberikan akses.

Jika aplikasi terdaftar di Developer Console dan telah disetujui untuk mengakses satu atau beberapa jenis perangkat, dan verifikasi brand telah diselesaikan untuk OAuth, aplikasi tersebut akan berada dalam status diverifikasi. 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 di Developer Console.

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

1. Pengguna akan diminta untuk memilih Akun Google yang ingin digunakan.
2. Pengguna akan diminta untuk memilih struktur yang ingin mereka beri akses ke aplikasi.
   1. Untuk aplikasi yang belum diverifikasi, semua jenis perangkat yang didukung oleh Home API tersedia untuk aplikasi tersebut.
   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 per perangkat. Misalnya, jika pengguna memiliki tiga smart lock, dia hanya dapat memberikan akses ke salah satu smart lock tersebut.

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

Ubah izin

Untuk memberikan izin akses 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 forcePermissionFlow ditetapkan ke ForcePermissionFlow.FORCE_LAUNCH:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Mengubah izin dengan prapemilihan struktur

Prapemilihan struktur memungkinkan aplikasi memilih struktur tertentu terlebih dahulu, atau membatasi daftar struktur yang tersedia, saat meminta perubahan inkremental pada izin Home API pengguna. Dengan meneruskan parameter struktur ke dalam permintaan otorisasi, dialog izin akan otomatis berfokus pada struktur yang dipilih, sehingga mengurangi hambatan pengguna dan mencegah error konfigurasi.

Prapemilihan struktur dikelola menggunakan class data ConsentScreenOptions. Class ConsentScreenOptions menerima parameter konfigurasi berikut:

• structureId — ID struktur tertentu yang akan dipilih sebelumnya dalam dialog izin. Dapatkan ID ini dengan memeriksa properti struktur untuk struktur yang sedang diperbarui.
• allowedStructureIds — Daftar ID struktur. Jika diberikan, dialog izin akan memfilter struktur yang tersedia untuk hanya menampilkan struktur yang ada dalam daftar ini. Hal ini dapat dibiarkan tidak ditentukan dalam sebagian besar kasus, kecuali jika Anda ingin memastikan pengguna tetap berada dalam daftar struktur yang telah diberikan.
• allowStructureChange — Menentukan apakah pengguna diizinkan untuk mengubah struktur yang telah dipilih sebelumnya. Tetapkan nilai ini ke true jika setidaknya salah satu dari allowedStructureIds dan structureId ditentukan dalam sebagian besar kasus untuk mendukung perilaku alami bagi pengguna.

Teruskan objek ini sebagai parameter opsional dalam panggilan requestPermissions(), dengan forcePermissionFlow ditetapkan ke ForcePermissionFlow.FORCE_LAUNCH:

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)

Pengguna akan melihat layar izin yang sudah difilter ke struktur yang tercantum dalam objek ConsentScreenOptions.

Mengizinkan pengguna beralih struktur dengan prapemilihan struktur

Jika pengguna memiliki beberapa struktur di aplikasi dan Anda ingin memilih salah satunya terlebih dahulu sambil tetap mengizinkan mereka beralih di antara struktur yang tersedia, aktifkan perubahan struktur dengan flag allowStructureChange dan berikan daftar struktur di allowedStructureIds:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

Mencabut izin

Pengguna dapat mencabut akses yang diberikan sebelumnya:

1. Melalui setelan Akun Google > 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.

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

Penghapusan dan ekspor data pengguna

Platform ini otomatis mengelola penghapusan data backend saat pengguna menghapus Akun Google mereka atau keluar dari struktur:

• Jika pengguna yang dihapus adalah pemilik tunggal struktur, platform akan menghapus struktur dan pengaitan perangkatnya.
• Jika pemilik lain tetap berada dalam struktur bersama, struktur dan perangkat bersamanya akan tetap ada untuk anggota yang tersisa. Platform akan menghapus keanggotaan pengguna yang keluar dan membatalkan tautan perangkat Cloud-to-cloud pihak ketiga yang terhubung hanya melalui kredensial pengguna tersebut.
• Penghapusan akun akan segera dan secara permanen menghapus data struktur dan izin aplikasi pengguna. Meskipun jika pengguna nantinya memulihkan Akun Google-nya, struktur dan izinnya tidak akan dipulihkan.

Home API tidak menyediakan endpoint untuk mengekspor atau menghapus data Akun Google pengguna. Arahkan pengguna yang memiliki Akun Google ke Google Takeout untuk mengekspor data Google Home mereka dan ke setelan Akun Google mereka untuk mengelola penghapusan akun.

Melihat jenis perangkat yang izinnya telah diberikan oleh pengguna

Dalam ekosistem Google Home, untuk sebagian besar jenis perangkat, pengguna dapat memberikan izin untuk semua perangkat dengan jenis tersebut sekaligus. Untuk jenis perangkat yang sensitif atau dibatasi, seperti smart lock, kamera, atau bel pintu, pengguna harus memberikan izin ke perangkat tersebut satu per satu.

Untuk menentukan apakah pengguna telah memberikan izin untuk mengakses jenis perangkat yang sensitif atau dibatasi, gunakan fungsi consentedDeviceTypes() level Struktur:

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

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.

Panduan jika pengguna mencabut izin penuh

Jika pengguna mencabut izin penuh, semua otomatisasi yang ada akan berhenti berfungsi. Selain itu, jika pengguna mencabut akses ke perangkat tertentu, pemicu, kondisi, dan tindakan yang terkait dengan perangkat tersebut akan berhenti berfungsi.

Setiap kali aplikasi dimulai, pastikan untuk memeriksa apakah izin masih berlaku. Jika izin telah dicabut, pastikan semua data sebelumnya dihapus, termasuk data yang di-cache dalam aplikasi.

Saat akses struktur dicabut, StructureAccessRevokedEvent akan dikirim ke backend cloud Anda. Lihat Izin struktur untuk alur kerja pencabutan aplikasi seluler dan cloud partner secara menyeluruh.