Commissioning API trên Android

Commissioning API cho phép một ứng dụng uỷ quyền cho một trong hai trường hợp sau:

  • Vải của bạn và vải của Google.
  • Chỉ có vải của Google.

Các cách thiết lập thiết bị Matter

Bạn có thể bắt đầu quy trình thiết lập:

Yêu cầu thiết lập trực tiếp trong ứng dụng

Bạn có thể yêu cầu thiết lậ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 vải đơn

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

  1. Khởi động một ActivityResultLauncher trong hoạt động của bạn. Nếu người dùng đã thiết lập thiết bị trên hệ thống 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 thiết lậ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 lựa chọn để uỷ quyền cho thiết bị vào cấu trúc 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 đưa thiết bị vào cả hệ thống của Google và hệ thống của riêng bạn, hãy thiết lập dịch vụ đưa vào sử dụng bằng setCommissioningService trong CommissioningRequest.

  3. Sử dụng thực thể CommissioningClient để bắt đầu quá trình thiết lập:

    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 liên kết (nhiều quản trị viên)

Nếu bạn cần thiết lập nhiều Matter 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 thiết lậ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 thiết lậ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 vải đơn

Sử dụng bộ lọc ý định ACTION_START_COMMISSIONING để cung cấp đầy đủ khả năng thiết lập cho một ứng dụng mà không cần GHA. Khi thiết lập cho Google Fabric, 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 thiết lập bằng ACTION_START_COMMISSIONING

Để cho biết khả năng hỗ trợ quy trình thiết lập của Google, hãy thêm intent-filter sau đây vào 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 ứng dụng Matter được đề xuất trong trình chọn ứng dụng của API khởi tạo. 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 lựa 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 một ý định ACTION_START_COMMISSIONING.

Đối với nhiều cấu trúc liên kết (nhiều quản trị viên)

Bạn cũng có thể sử dụng quy trình FastPair trong 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 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 nên huỷ quá trình thiết lập.

Tắt thông báo về nội dung có thể kiếm hoa hồng

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 dạng tờ rơi một nửa trên Android

Theo mặc định, Google Play services trên Android sẽ sử dụng thông báo "halfsheet" (nửa trang) bao phủ nửa dưới màn hình của thiết bị di động để cung cấp cho người dùng một chỉ báo chủ động rằng các thiết bị Matter có thể uỷ quyền đang ở gần.

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

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

Làm cách nào để chia sẻ các thiết bị Matter trên mạng lưới của bạn với Google?

Bạn nên sử dụng Commissioning API làm phương thức chính để chia sẻ thiết bị mà bạn đã thiết lập trên mạng lưới của riêng mình với mạng lướ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 tính năng chia sẻ thiết bị trực tiếp với Google Fabric. Đây là phương thức nên ưu tiên khi có thể. Với Share API, người dùng cuối cần 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à họ phải biết cách chọn GHA trong quy trình để đảm bảo thành công.

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

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

Bạn có thể 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.