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.

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

Mengintegrasikan Permissions API

Sebelum melanjutkan, pastikan Anda telah mengikuti Menginisialisasi rumah di Android. Instance homeManager dari langkah tersebut digunakan di semua contoh Izin di sini.

Pertama, daftarkan ActivityResultCaller dengan SDK. Misalnya, seperti inilah 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() dari 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, berarti pengguna atau aplikasi tidak memiliki akses ke struktur. Jika pemeriksaan menampilkan PermissionsState dari 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 agar dapat 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 telah menyiapkan OAuth untuk aplikasi.

Memberikan 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. Pendaftaran tidak diperlukan untuk menguji dan menggunakan Home API.

Jika aplikasi tidak terdaftar di Developer Console, aplikasi akan berada dalam status belum diverifikasi. Status 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 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 diberikan.

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

• Batas pengguna uji coba tidak lagi berlaku. Pengguna mana pun dapat memberikan izin ke aplikasi.
• Pengguna hanya dapat memberikan izin ke jenis perangkat yang disetujui di the 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 akan diminta memilih struktur yang ingin mereka berikan akses aplikasi.
   1. Untuk aplikasi yang belum diverifikasi, semua jenis perangkat yang didukung oleh Home API tersedia untuk aplikasi.
   2. Untuk aplikasi yang 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 dapat memberikan akses hanya 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.

Mengubah 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)

Mengubah izin dengan petunjuk struktur

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

Petunjuk 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 dalam daftar ini. Parameter 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 mengubah struktur yang telah dipilih sebelumnya. Tetapkan parameter ini ke true jika setidaknya salah satu dari allowedStructureIds dan structureId ditentukan dalam sebagian besar kasus untuk mendukung perilaku alami pengguna.

Teruskan objek ini sebagai parameter opsional dalam panggilan requestPermissions(), dengan tanda forceLaunch yang ditetapkan ke true:

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(forceLaunch=true, consentOptions)

Pengguna akan melihat layar izin yang telah difilter ke struktur yang tercatat dalam objek ConsentScreenOptions.

Mengizinkan pengguna beralih struktur dengan petunjuk struktur

Jika pengguna memiliki beberapa struktur dalam aplikasi dan Anda ingin memilih salah satunya sebelumnya sambil tetap mengizinkan mereka beralih di antara struktur yang tersedia, aktifkan perubahan struktur dengan tanda 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 telah diberikan sebelumnya:

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

Melihat jenis perangkat yang telah diberikan izin oleh pengguna

Di ekosistem Google Home, untuk sebagian besar jenis perangkat, pengguna dapat memberikan izin untuk semua perangkat dari jenis tersebut sekaligus. Untuk jenis perangkat sensitif atau terbatas, seperti kunci, kamera, atau bel pintu, pengguna harus memberikan izin satu per satu.

Untuk menentukan apakah pengguna telah memberikan izin untuk mengakses jenis perangkat sensitif atau terbatas, gunakan fungsi consentedDeviceTypes() tingkat 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 di aplikasi.