Permissions API trên Android

Trước khi sử dụng bất kỳ API Home nào cho Android, ứng dụng phải có quyền truy cập vào các thiết bị trong nhà của người dùng (trong API được gọi là cấu trúc). Với API Quyền, người dùng có thể cấp cho các ứng dụng API Home quyền truy cập vào các thiết bị trong nhà của họ bằng Tài khoản Google.

Quy trình cấp quyền cho phép người dùng tạo cấu trúc (nếu chưa thiết lập) mà không cần sử dụng Google Home app (GHA).

Tích hợp API Quyền

Trước khi tiếp tục, hãy đảm bảo bạn đã làm theo phần Khởi chạy nhà trên Android. Phiên bản homeManager từ bước đó được dùng trong tất cả các ví dụ về Quyền ở đây.

Trước tiên, hãy đăng ký một ActivityResultCaller bằng SDK. Ví dụ: đây là cách Ứng dụng mẫu xử lý việc này:

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

Kiểm tra quyền

Trước khi yêu cầu cấp quyền, bạn nên kiểm tra xem người dùng ứng dụng đã đồng ý cấp quyền truy cập vào cấu trúc hay chưa. Để làm việc này, hãy gọi phương thức hasPermissions() của thực thể Home để lấy Flow của PermissionsState các giá trị:

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

Nếu quy trình kiểm tra trả về PermissionsState là NOT_GRANTED hoặc PERMISSIONS_STATE_UNAVAILABLE, thì có nghĩa là người dùng hoặc ứng dụng không có quyền truy cập vào cấu trúc. Nếu quy trình kiểm tra trả về PermissionsState là GRANTED nhưng lệnh gọi tiếp theo đến structures() không trả về cấu trúc nào, thì có nghĩa là người dùng đã thu hồi quyền truy cập vào ứng dụng thông qua trang cài đặt GHA hoặc người dùng không có quyền truy cập cần thiết.

Yêu cầu cấp quyền

Bạn phải cấp quyền cho ứng dụng của mình để truy cập vào các cấu trúc và thiết bị trong một cấu trúc nhất định.

Nếu người dùng chưa cấp quyền, hãy sử dụng phương thức requestPermissions() của thực thể Home để khởi chạy giao diện người dùng Quyền và xử lý kết quả:

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

Để giao diện người dùng Quyền khởi chạy đúng cách, bạn phải đã thiết lập OAuth cho ứng dụng của mình.

Cấp quyền

Giờ đây, bạn có thể chạy ứng dụng và yêu cầu người dùng cấp quyền. Loại người dùng có thể cấp quyền và loại thiết bị có thể được cấp quyền sẽ khác nhau tuỳ thuộc vào việc bạn đã đăng ký ứng dụng của mình trong Google Home Developer Console hay chưa.

Bạn phải đăng ký Developer Console để phát hành ứng dụng bằng API Home. Bạn không cần đăng ký để kiểm thử và sử dụng API Home.

Nếu ứng dụng chưa được đăng ký trong Developer Console, thì ứng dụng sẽ ở trạng thái chưa xác minh. Bạn nên sử dụng trạng thái này để kiểm thử việc sử dụng API Home:

• Chỉ những người dùng đã đăng ký làm người dùng kiểm thử trong bảng điều khiển OAuth mới có thể cấp quyền cho ứng dụng. Ứng dụng chưa xác minh chỉ có thể có tối đa 100 người dùng kiểm thử.

• Ứng dụng chưa xác minh sẽ có quyền truy cập vào các thiết bị thuộc mọi loại thiết bị được OAuth hỗ trợ cho API Home (danh sách loại thiết bị trong Developer Console). Tất cả các thiết bị trong một cấu trúc sẽ được cấp quyền.

Nếu ứng dụng được đăng ký trong Developer Console và đã được phê duyệt để truy cập vào một hoặc nhiều loại thiết bị, đồng thời đã hoàn tất quy trình xác minh thương hiệu cho OAuth, thì ứng dụng sẽ ở trạng thái đã xác minh. Bạn phải ở trạng thái này để chạy ứng dụng trong môi trường thực tế:

• Không còn áp dụng hạn mức người dùng thử nghiệm. Mọi người dùng đều có thể cấp quyền cho ứng dụng.
• Người dùng chỉ có thể cấp quyền cho các loại thiết bị đã được phê duyệt trong Developer Console.

Sau khi bạn thiết lập OAuth, lệnh gọi của ứng dụng đến requestPermissions() sẽ kích hoạt các hộp thoại sau:

1. Người dùng sẽ được nhắc chọn Tài khoản Google mà họ muốn sử dụng.
2. Người dùng sẽ được nhắc chọn cấu trúc mà họ muốn cấp quyền truy cập cho ứng dụng.
   1. Đối với ứng dụng chưa xác minh, ứng dụng có thể sử dụng tất cả các loại thiết bị được API Home hỗ trợ.
   2. Đối với ứng dụng đã xác minh, người dùng chỉ có thể cấp quyền cho các loại thiết bị đã được phê duyệt trong Developer Console.
   3. Đối với các loại thiết bị nhạy cảm mà ứng dụng có quyền quản lý, người dùng có thể hạn chế quyền truy cập theo từng thiết bị. Ví dụ: nếu người dùng có 3 ổ khoá, họ chỉ có thể cấp quyền truy cập vào một trong số đó.

Sau khi được cấp quyền, ứng dụng có thể sử dụng API Home để đọc trạng thái và điều khiển các thiết bị trong cấu trúc. Nếu người dùng không cấp quyền cho ứng dụng đối với một loại thiết bị cụ thể hoặc thiết bị nhạy cảm, thì ứng dụng sẽ không thể sử dụng API Home để truy cập, điều khiển hoặc tự động hoá thiết bị đó.

Thay đổi quyền

Để cấp quyền truy cập vào các thiết bị trong một cấu trúc khác, bạn có thể khởi chạy trình chọn tài khoản để cho phép người dùng chọn Tài khoản Google và cấu trúc mà họ muốn chuyển sang. Trong quá trình này, người dùng sẽ thấy lại màn hình xin phép, ngay cả khi họ đã đồng ý trước đó.

Bạn có thể thực hiện việc này bằng cách gọi lại requestPermissions() với cờ forceLaunch được đặt thành true:

homeManager.requestPermissions(forceLaunch=true)

Thay đổi quyền bằng cách gợi ý cấu trúc

Tính năng gợi ý cấu trúc cho phép ứng dụng chọn trước một cấu trúc cụ thể hoặc hạn chế danh sách các cấu trúc hiện có khi yêu cầu thay đổi tăng dần đối với quyền API Home của người dùng. Bằng cách truyền các tham số cấu trúc vào yêu cầu uỷ quyền, hộp thoại quyền sẽ tự động tập trung vào cấu trúc đã chọn, giảm bớt sự khó chịu cho người dùng và ngăn ngừa lỗi cấu hình.

Bạn có thể quản lý tính năng gợi ý cấu trúc bằng lớp dữ liệu ConsentScreenOptions. Lớp ConsentScreenOptions chấp nhận các tham số cấu hình sau:

• structureId – Mã cấu trúc cụ thể để chọn trước trong hộp thoại quyền. Bạn có thể lấy mã này bằng cách kiểm tra các thuộc tính cấu trúc cho cấu trúc đang được cập nhật.
• allowedStructureIds – Danh sách mã cấu trúc. Nếu được cung cấp, hộp thoại quyền sẽ lọc các cấu trúc hiện có để chỉ hiển thị những cấu trúc trong danh sách này. Trong hầu hết các trường hợp, bạn có thể không chỉ định tham số này, trừ phi bạn muốn đảm bảo người dùng vẫn ở trong danh sách cấu trúc đã được cấp quyền.
• allowStructureChange – Xác định xem người dùng có được phép thay đổi cấu trúc đã chọn trước hay không. Trong hầu hết các trường hợp, hãy đặt tham số này thành true nếu bạn chỉ định ít nhất một trong các tham số allowedStructureIds và structureId để hỗ trợ hành vi tự nhiên của người dùng.

Truyền đối tượng này dưới dạng tham số không bắt buộc trong lệnh gọi requestPermissions(), với cờ forceLaunch được đặt thành 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)

Người dùng sẽ thấy màn hình xin phép đã được lọc theo cấu trúc được ghi chú trong đối tượng ConsentScreenOptions.

Cho phép người dùng chuyển đổi cấu trúc bằng tính năng gợi ý cấu trúc

Nếu người dùng có nhiều cấu trúc trong một ứng dụng và bạn muốn chọn trước một cấu trúc trong khi vẫn cho phép họ chuyển đổi giữa các cấu trúc hiện có, hãy bật các thay đổi cấu trúc bằng cờ allowStructureChange và cung cấp danh sách cấu trúc trong allowedStructureIds:

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

Thu hồi quyền

Người dùng có thể thu hồi quyền truy cập đã cấp trước đó:

1. Thông qua trang Google MyAccounts > Dữ liệu và quyền riêng tư > Ứng dụng và dịch vụ của bên thứ ba. Thao tác này sẽ thu hồi mã thông báo OAuth đã được cấp khi người dùng đồng ý lần đầu và sẽ thu hồi quyền truy cập vào mọi thực thể của ứng dụng mà người dùng đang sử dụng trên tất cả các nền tảng (điện thoại) và cấu trúc.

   Người dùng có thể được chuyển hướng bằng liên kết sâu đến trang con Ứng dụng và dịch vụ của bên thứ ba bằng cách sử dụng lược đồ URL sau:

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

2. Thông qua trang GHA > Cài đặt > Ứng dụng được liên kết. Khi nhấp vào settings trong GHA, bạn sẽ được chuyển đến trang Cài đặt. Từ đó, hãy nhấp vào ô Ứng dụng được liên kết để chuyển đến một trang có giao diện tương tự như màn hình xin phép. Trên trang này, người dùng có thể xoá quyền truy cập vào ứng dụng. Người dùng có thể sử dụng trang này để thay đổi loại thiết bị hoặc thiết bị nhạy cảm cụ thể mà ứng dụng có thể truy cập.

Xem các loại thiết bị mà người dùng đã cấp quyền

Trong hệ sinh thái Google Home, đối với hầu hết các loại thiết bị, người dùng có thể cấp quyền cho tất cả các thiết bị thuộc loại đó cùng một lúc. Đối với các loại thiết bị nhạy cảm hoặc bị hạn chế, chẳng hạn như ổ khoá, camera hoặc chuông cửa, người dùng phải cấp quyền cho từng thiết bị.

Để xác định xem người dùng đã cấp quyền truy cập vào một loại thiết bị nhạy cảm hoặc bị hạn chế hay chưa, hãy sử dụng hàm consentedDeviceTypes() ở cấp Cấu trúc:

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

Quyền OkGoogle

Lệnh okGoogle là lệnh ở cấp thiết bị và có thể dùng để tự động hoá mọi thiết bị trong cấu trúc. Tuy nhiên, ứng dụng API Home có thể không có quyền truy cập vào mọi thiết bị. Bảng sau đây mô tả cách thực thi quyền trong những trường hợp như vậy.

Hướng dẫn nếu người dùng thu hồi toàn bộ quyền

Nếu người dùng thu hồi toàn bộ quyền, tất cả các quy trình tự động hoá hiện có sẽ ngừng hoạt động. Ngoài ra, nếu người dùng thu hồi quyền truy cập vào các thiết bị cụ thể, thì các trình khởi chạy, điều kiện và hành động được liên kết với các thiết bị đó sẽ ngừng hoạt động.

Mỗi khi ứng dụng khởi động, hãy nhớ kiểm tra để đảm bảo các quyền vẫn còn hiệu lực. Nếu các quyền đã bị thu hồi, hãy đảm bảo rằng tất cả dữ liệu trước đó đều bị xoá, bao gồm cả mọi dữ liệu được lưu vào bộ nhớ đệm trong ứng dụng.