Commissioning API на Android

Commissioning API позволяет приложению вводить в эксплуатацию:

  • Ваша ткань и ткань Google.
  • Только ткань Google.

Как инициализировать устройства Matter

Процесс ввода в эксплуатацию можно запустить:

Запросите ввод в эксплуатацию прямо в приложении.

Запрос на ввод в эксплуатацию можно отправить прямо из приложения, нажав кнопку. Это можно сделать двумя способами:

Для отдельных тканей

Чтобы запросить ввод в эксплуатацию:

  1. Инициализируйте объект ActivityResultLauncher в своем действии. Если пользователь ввел устройство в эксплуатацию в сети Google, результат может включать название, которое пользователь присвоил устройству при вводе в эксплуатацию.

    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. Создайте объект CommissioningRequest, включая полученные данные полезной нагрузки, и задайте параметр, чтобы добавить устройство в фабрику Google, используя setStoreToGoogleFabric.

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

    Если вы хотите ввести устройство в эксплуатацию в фабрике Google и собственной фабрике, настройте сервис ввода в эксплуатацию с помощью setCommissioningService в CommissioningRequest.

  3. Чтобы начать ввод в эксплуатацию, используйте экземпляр CommissioningClient:

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

    где _commissioningIntentSender определяется следующим образом:

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

  4. После того как CommissioningClient вернет отправителя intent, запустите его:

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

Для нескольких сетей (несколько администраторов)

Если вам нужно настроить несколько сетей Matter на устройстве, ознакомьтесь с информацией о Multi-admin для Commissioning API на Android.

Точка входа для ввода в эксплуатацию устройств Matter с помощью быстрого подключения или сканирования QR-кода (только для Android)

Запросить ввод в эксплуатацию с помощью быстрого подключения или QR-кода на Android можно двумя способами:

Для отдельных тканей

Используйте фильтр интентов ACTION_START_COMMISSIONING, чтобы обеспечить полную поддержку ввода в эксплуатацию для приложения без GHA. При вводе в эксплуатацию в сети Google пользователь может присвоить устройству название.

Процесс инициализации с использованием ACTION_START_COMMISSIONING
Рисунок 1. Процесс ввода в эксплуатацию с помощью ACTION_START_COMMISSIONING

Чтобы указать поддержку ввода в эксплуатацию в сети Google, добавьте следующий элемент intent-filter в выбранное объявление действия в файле 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 используется, чтобы добавить ваше приложение в список рекомендуемых приложений Matter в окне выбора приложений Commissioning API. Если вашего приложения нет в списке, нажмите Выбрать другое приложение.

После того как пользователь выберет ваше приложение, оно запустится и перейдет к выбранному действию с намерением ACTION_START_COMMISSIONING.

Для нескольких сетей (несколько администраторов)

Вы также можете использовать Fast Pair в сценариях с несколькими администраторами. Подробную информацию можно найти в статье Multi-admin for Commissioning API on Android (Несколько администраторов для Commissioning API на Android).

Обработка входящего намерения

После запуска действия оно должно проверить наличие намерения ACTION_START_COMMISSIONING и получить полезную нагрузку:

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)
}

Значение полезной нагрузки, отличное от null, указывает на то, что пользователь уже отсканировал QR-код устройства или ввел ключ подключения. Значение полезной нагрузки null не означает, что ввод в эксплуатацию должен быть прерван.

Отключить уведомления о комиссионных

Пример уведомления на половину экрана в Android
Рисунок 1. Пример уведомления на половину экрана на устройстве Android

По умолчанию Google Play services на Android использует уведомления в виде полустраницы, которые закрывают нижнюю половину экрана мобильного устройства и сообщают пользователям о том, что поблизости есть устройства Matter, которые можно ввести в эксплуатацию.

Чтобы не прерывать работу приложения, когда оно находится на переднем плане, вы можете отключить эти уведомления, вызвав метод suppressHalfSheetNotification(). Дополнительную информацию можно найти в документации по API.

Если приложение находится на переднем плане более 15 минут, срок действия подавления, включенного этим API, истекает. Чтобы снова включить подавление после тайм-аута, вызовите suppressHalfSheetNotification() ещё раз. В противном случае уведомления на пол-экрана начнут появляться снова.

Как предоставить Google доступ к устройствам Matter в вашей сети?

Мы настоятельно рекомендуем использовать Commissioning API в качестве основного средства для предоставления доступа к устройству, которое вы уже настроили в своей сети, сети Google. У Share API есть ограничения, и его следует использовать для других целей.

Почему стоит использовать Commissioning API вместо Share API?

Commissioning API позволяет запустить процесс предоставления доступа к устройству напрямую в фабрику Google. Это предпочтительный метод, если он доступен. При использовании Share API конечному пользователю нужно выполнить больше действий. Например, у конечного пользователя должно быть установлено приложение GHA, и он должен знать, что в процессе нужно выбрать GHA.

Чтобы использовать Commissioning API, откройте окно ввода в эксплуатацию и вызовите Commissioning API, как описано в разделе Как использовать Commissioning API в качестве дополнительного уполномоченного Matter.

Когда следует использовать Share API?

Вы можете использовать Share API, чтобы конечный пользователь мог выбрать подходящее приложение и предоставить доступ к устройству другим экосистемам Matter.