Commissioning API trên Android

Commissioning API cho phép một ứng dụng cấp phép cho:

  • Loại vải của bạn và loại vải của Google.
  • Chỉ loại vải của Google.

Cách cấp phép cho các thiết bị Matter

Bạn có thể bắt đầu quy trình cấp phép:

Yêu cầu cấp phép trực tiếp trong ứng dụng

Bạn có thể yêu cầu cấp phép trực tiếp trong ứng dụng bằng cách nhấn vào một nút trong ứng dụng. Bạn có thể thực hiện việc này theo 2 cách:

Đối với một loại vải

Cách yêu cầu cấp phép:

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

    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 CommissioningRequest, bao gồm cả dữ liệu tải trọng đã nhận được và đặt tuỳ chọn cấp phép cho thiết bị trên loại vải của Google bằng cách sử dụ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 cấp phép cho thiết bị trên loại vải của Google cũng như loại vải của riêng mình, hãy đặt dịch vụ cấp phép bằng setCommissioningService trong CommissioningRequest.

  3. Sử dụng thực thể để bắt đầu cấp phép:CommissioningClient

    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 chạy trình gửi:

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

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

Nếu bạn cần thiết lập nhiều Matter loại vải trên một thiết bị, hãy tham khảo Nhiều quản trị viên cho Commissioning API trên Android.

Điểm truy cập cấp phép Matter cho tính năng Ghép nối nhanh hoặc quét mã QR (chỉ dành cho Android)

Bạn có thể yêu cầu cấp phép bằng tính năng ghép nối nhanh hoặc mã QR trên Android theo 2 cách:

Đối với một loại vải

Sử dụng bộ lọc ý định ACTION_START_COMMISSIONING để cung cấp đầy đủ khả năng cấp phép cho một ứng dụng mà không cần GHA. Khi cấp phép cho loại vải của Google, điều này bao gồm việc cho phép người dùng chỉ định tên cho thiết bị.

Quy trình thiết lập bằng ACTION_START_COMMISSIONING
Hình 1: Quy trình cấp phép bằng ACTION_START_COMMISSIONING

Để cho biết khả năng hỗ trợ cấp phép cho loại vải của Google, 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 Commissioning APIs. Nếu ứng dụng của bạn không nằm trong số các ứng dụng được đề xuất, thì ứng dụng đó 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 đến hoạt động đã chọn bằng ý định ACTION_START_COMMISSIONING.

Đối với nhiều loại vải (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 Nhiều quản trị viên cho Commissioning API trên Android.

Xử lý ý định đến

Sau khi hoạt động của bạn được 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à quá trình cấp phép phải bị huỷ.

Ngăn thông báo phát hiện có thể cấp phép

Ví dụ về thông báo dạng tờ rơi một nửa trên Android
Hình 1: Ví dụ về thông báo nửa trang tính trên Android

Theo mặc định, Google Play services trên Android sử dụng thông báo "nửa trang tính" bao phủ nửa dưới màn hình của thiết bị di động để chủ động cho người dùng biết rằng có các thiết bị Matter có thể cấp hoa hồng ở gần đó.

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

Tính năng ngăn chặn do API này bật sẽ hết thời gian chờ nếu ứng dụng của bạn ở nền trước trong hơn 15 phút. Để bật lại tính năng ngăn 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 tính sẽ bắt đầu xuất hiện.

Bạn nên chia sẻ các thiết bị Matter trên loại vải của mình với Google như thế nào?

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

Tại sao bạn nên sử dụng Commissioning API thay vì Share API?

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

Để sử dụng Commissioning API, bạn nên mở cửa sổ cấp phép và gọi Commissioning API, như mô tả trong bài viết Cách sử dụng Commissioning API làm trình cấp phép Matter thứ cấp.

Bạn nên sử dụng Share API khi nào?

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ẻ thiết bị một cách chung chung với các hệ sinh thái Matter khác.