Commissioning API trên Android

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

  • Cấu trúc của bạn và cấu trúc của Google.
  • Chỉ cấu trúc 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 của bạn

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 và có thể thực hiện theo 2 cách:

Đối với một cấu trúc

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

  1. Khởi chạy một 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 cấu trúc 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 một 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 cấu trúc 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 cấu trúc của Google cũng như cấu trúc của riêng bạn 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 cấu trúc (nhiều quản trị viên)

Nếu bạn cần thiết lập nhiều Matter cấu trúc trên một thiết bị, hãy tham khảo bài viết 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 cấu trúc

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 cấu trúc của Google, việc này bao gồm 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 bạn hỗ trợ cấp phép cho cấu trúc 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 được đề xuất Matter trong trình chọn ứng dụng của Commissioning API. Nếu ứng dụng của bạn không phải là một trong 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ẽ chạy và chuyển đến hoạt động đã chọn bằng ý định ACTION_START_COMMISSIONING.

Đối với nhiều cấu trúc (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 chạy, hoạt động của bạn 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
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ỷ quy trình cấp phép.

Ngăn thông báo về việc phát hiện thiết bị 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 trên Android

Theo mặc định, Google Play services trên Android sử dụng thông báo "nửa trang" bao phủ nửa dưới màn hình của thiết bị di động để cho người dùng biết một cách chủ động rằng các thiết bị Matter có thể cấp phép ở 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 sẽ bắt đầu xuất hiện.

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

Google khuyên 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 cấu trúc của riêng mình với cấu trúc của Google. Share API có những hạn chế và chỉ nên dùng 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 cấu trúc của Google. Đây là phương thức ưu tiên khi có thể. 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ứ hai.

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

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.