API Ủy quyền

API uỷ quyền cho phép ứng dụng uỷ quyền cho:

  • Fabric của bạn và fabric của Google.
  • Chỉ có Google fabric.

Cho biết bạn hỗ trợ việc uỷ quyền Matter

Nếu đang sử dụng Google Home Mobile SDK để uỷ quyền, bạn phải thêm tên gói ứng dụng trong Google Home Developer Console, triển khai API Matter và cho biết ứng dụng của bạn hỗ trợ uỷ quyền Matter bằng cách xử lý ý định ACTION_COMMISSION_DEVICE.

Thêm intent-filter sau vào phần khai báo application trong tệp AndroidManifest.xml:

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

Hãy xem tệp kê khai của ứng dụng mẫu để tham khảo.

Các cách nhận hoa hồng cho thiết bị Matter

Bạn có thể bắt đầu quy trình uỷ quyền:

Yêu cầu uỷ quyền ngay trong ứng dụng

Bạn có thể kích hoạt yêu cầu uỷ quyền ngay trong ứng dụng bằng một nút trong ứng dụng và có thể thực hiện theo hai cách:

Đối với vải đơn

Cách yêu cầu uỷ quyền:

  1. Khởi chạy ActivityResultLauncher trong hoạt động của bạn. Nếu người dùng đã uỷ quyền thiết bị trên Google Fabric, kết quả có thể bao gồm tên mà người dùng chỉ định cho thiết bị khi uỷ quyền thiết bị đó.

    private val commissioningLauncher =
  registerForActivityResult(StartIntentSenderForResult()) { result ->
    val resultCode = result.resultCode
    if (resultCode == RESULT_OK) {
        Log.i("CommissioningActivity", "Commissioning success")
  val deviceName =
          CommissioningResult.fromIntentSenderResult(result.resultCode, result.data).deviceName
      } else {
          Log.i("CommissioningActivity", "Commissioning failed")
      }
    }

  2. Tạo một CommissioningRequest, bao gồm cả dữ liệu tải trọng đã nhận và đặt tuỳ chọn uỷ quyền thiết bị cho Google Fabric bằng setStoreToGoogleFabric:

    val commissioningRequest = CommissioningRequest.builder()
        .setOnboardingPayload(payload)
        .setStoreToGoogleFabric(true)
  // set all other options that you care about
        .build()

    Nếu bạn muốn uỷ quyền cho thiết bị cho Google Fabric cũng như Fabric của riêng mình, hãy thiết lập dịch vụ uỷ quyền bằng setCommissioningService trong CommissioningRequest.

  3. Sử dụng thực thể CommissioningClient để bắt đầu uỷ quyền:

    commissioningClient
  .commissionDevice(commissioningRequest)
  .addOnSuccessListener { result ->
    Log.i("CommissioningActivity", "Commissioning success")
_commissioningIntentSender.postValue(result)
      }
      .addOnFailureListener { error ->
        Log.i("CommissioningActivity", "Commissioning failed")
  }

    Trong đó, _commissioningIntentSender được xác định là:

    private val _commissioningIntentSender = MutableLiveData<IntentSender?>()
    val commissioningIntentSender: LiveData<IntentSender?>
    get() = _commissioningIntentSender

  4. Sau khi CommissioningClient trả về trình gửi ý định, hãy khởi chạy trình gửi:

    commissioningIntentSender.observe(this) { sender ->
  if (sender != null) {
    commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build())
  }
}

Đối với nhiều Fabric (nhiều quản trị viên)

Nếu bạn cần thiết lập nhiều fabric Matter trên một thiết bị, hãy tham khảo phần Cách sử dụng API uỷ quyền ở chế độ nhiều quản trị viên.

Điểm truy cập uỷ quyền Matter để ghép nối nhanh hoặc quét mã QR (chỉ dành cho Android)

Bạn có thể yêu cầu uỷ quyền bằng cách ghép nối nhanh hoặc mã QR trên Android theo hai cách:

Đối với vải đơn

Sử dụng bộ lọc ý định ACTION_START_COMMISSIONING để cung cấp toàn bộ chức năng uỷ quyền cho một ứng dụng mà không cần GHA. Khi uỷ quyền cho Google Fabric, bạn sẽ cho phép người dùng chỉ định tên cho thiết bị.

Quy trình uỷ quyền bằng cách sử dụng ACTION_START_COMMISSIONING
Hình 1: Quy trình uỷ quyền bằng cách sử dụng ACTION_START_COMMISSIONING

Để cho biết việc hỗ trợ uỷ quyền Google Fabric, hãy thêm intent-filter sau vào phần khai báo hoạt động đã chọn trong tệp AndroidManifest.xml:

<intent-filter>
  <action android:name="com.google.android.gms.home.matter.ACTION_START_COMMISSIONING" />
  <category android:name="android.intent.category.DEFAULT" />
 </intent-filter>

intent-filter được dùng để đưa ứng dụng của bạn vào danh sách các ứng dụng Matter được đề xuất trong trình chọn ứng dụng của API uỷ quyền. Nếu không phải là một trong các ứng dụng được đề xuất, ứng dụng của bạn sẽ xuất hiện trong tuỳ chọn Chọn ứng dụng khác.

Sau khi người dùng chọn ứng dụng của bạn, ứng dụng sẽ được chạy và chuyển hướng đến hoạt động đã chọn bằng ý định ACTION_START_COMMISSIONING.

Đối với nhiều Fabric (nhiều quản trị viên)

bạn cũng có thể sử dụng quy trình FastPair trong các trường hợp có nhiều quản trị viên. Để biết thêm thông tin, hãy tham khảo bài viết Cách sử dụng API uỷ quyền ở chế độ nhiều quản trị viên.

Xử lý ý định đến

Sau khi khởi chạy, hoạt động sẽ kiểm tra ý định ACTION_START_COMMISSIONING hiện có và truy xuất tải trọng:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

val payload = if (Matter.ACTION_START_COMMISSIONING.equals(intent.getAction())) {
      intent.getStringExtra(Matter.EXTRA_ONBOARDING_PAYLOAD)
    } else {
      null
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
startCommissioning(commissioningRequest)
}

Giá trị tải trọng không phải là null cho biết người dùng đã quét mã QR của thiết bị hoặc nhập khoá ghép nối. Giá trị tải trọng null không có nghĩa là bạn phải huỷ quá trình uỷ quyền.

Tắt thông báo khám phá có thể nhận được tiền hoa hồng

Ví dụ về thông báo nửa trang trên Android
Hình 1: Ví dụ về thông báo nửa trang trên Android

Theo mặc định, Google Play services trên Android sử dụng thông báo "halfsheet" (nửa trang) bao phủ nửa dưới của màn hình thiết bị di động để cung cấp cho người dùng thông tin chủ động về việc các thiết bị Matter có thể nhận được tiền hoa hồng đang ở gần.

Để ngăn chặn sự gián đoạn khi ứng dụng đang chạy trên nền trước, bạn có thể bịt các thông báo này bằng cách gọi phương thức suppressHalfSheetNotification() trong Mobile SDK. Hãy xem tài liệu về API để biết thêm thông tin.

Tính năng chặn do API này bật sẽ hết thời gian chờ nếu ứng dụng của bạn chạy ở nền trước trong hơn 15 phút. Để bật lại tính năng chặn sau khi hết thời gian chờ, hãy gọi lại suppressHalfSheetNotification(), nếu không, thông báo nửa trang sẽ bắt đầu xuất hiện.

Bạn có thể tìm thấy cách triển khai API này trong Google Home Sample App for Matter. Hãy xem HalfSheetSuppressionObserver.kt để biết thêm thông tin.

Bạn nên chia sẻ các thiết bị Matter trên Fabric với Google như thế nào?

Bạn nên sử dụng API uỷ quyền làm phương thức chính để chia sẻ một thiết bị mà bạn đã thiết lập trên fabric của riêng mình với fabric của Google. Share API có những hạn chế và nên được dành riêng cho các trường hợp sử dụng khác.

Tại sao bạn nên sử dụng API uỷ quyền thay vì API chia sẻ?

API uỷ quyền cho phép bạn kích hoạt tính năng chia sẻ thiết bị trực tiếp với Google Fabric. Đây là phương thức ưu tiên khi có thể. Với API Share, người dùng cuối cần thực hiện thêm các bước. Ví dụ: người dùng cuối phải cài đặt GHA và họ phải biết chọn GHA trong quá trình này để đảm bảo thành công.

Để sử dụng API uỷ quyền, bạn nên mở cửa sổ uỷ quyền và gọi API uỷ quyền, như mô tả trong phần Cách sử dụng API uỷ quyền làm uỷ quyền viên phụ của Matter.

Khi nào bạn nên sử dụng API Chia sẻ?

Bạn có thể sử dụng Share API để cho phép người dùng cuối chọn một ứng dụng đủ điều kiện để chia sẻ chung một thiết bị với các hệ sinh thái Matter khác.

Trước
Khắc phục sự cố
Tiếp
Ủy quyền trải nghiệm người dùng