Commissioning API trên Android

Commissioning API cho phép một ứng dụng uỷ quyền cho:

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

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

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

Yêu cầu uỷ quyền trực tiếp trong ứng dụng

Bạn có thể kích hoạt yêu cầu uỷ quyền trực tiếp 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:

Cho một loại vải

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 cho thiết bị trên Google Fabric, thì 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.

    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 để uỷ quyền thiết bị cho cấu trúc Google 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 thiết bị cho cấu trúc Google cũng như cấu trúc của riêng bạn, hãy đặt 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 như sau:

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

  4. Sau khi CommissioningClient trả về ý định của người gửi, hãy khởi chạy người gửi:

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

Đối với nhiều mạng lưới (nhiều quản trị viên)

Nếu bạn cần thiết lập nhiều mạng Matter trên một thiết bị, hãy tham khảo bài viết Multi-admin for Commissioning API on Android (Nhiều quản trị viên cho API uỷ quyền trên Android).

Điểm truy cập để uỷ quyền 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 uỷ quyền bằng tính năng Ghép nối nhanh hoặc mã QR trên Android theo hai cách:

Cho một loại vải

Sử dụng bộ lọc ý định ACTION_START_COMMISSIONING để cung cấp đầy đủ 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, việc này bao gồm cả việc cho phép người dùng đặt tên cho thiết bị.

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

Để cho biết khả năng hỗ trợ cho việc uỷ quyền cấu trúc 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 ứng dụng Matter được đề xuất trong bộ chọn ứng dụng của API uỷ quyền. Nếu ứng dụng của bạn không phải là một trong những ứ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 ý định ACTION_START_COMMISSIONING.

Đối với nhiều mạng lưới (nhiều quản trị viên)

Bạn cũng có thể sử dụng quy trình Ghép nối nhanh 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 Multi-admin for Commissioning API on Android (Nhiều quản trị viên cho API uỷ quyền trên Android).

Xử lý ý định đến

Sau khi hoạt động đượ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
    }
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 nên huỷ bỏ quá trình uỷ quyền.

Ẩn thông báo về nội dung khám phá có thể nhậ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 "nửa trang" 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ể uỷ quyền ở gần.

Để tránh bị gián đoạn khi ứng dụng của bạn đang chạy trê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.

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 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 tính sẽ bắt đầu xuất hiện.

Làm cách nào để chia sẻ 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 tiện chính để chia sẻ 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à 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 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 ưu tiên khi khả thi. Với Share API, 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 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ổ uỷ quyền và gọi Commissioning API, như mô tả trong bài viết Cách sử dụng Commissioning API làm người uỷ quyền Matter phụ.

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

Bạn có thể sử dụng Share API (API Chia sẻ) để 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ị với các hệ sinh thái Matter khác.