API ввода в эксплуатацию

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

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

Указать поддержку ввода в эксплуатацию Материи

Если вы используете Google Home Mobile SDK для ввода в эксплуатацию, вам необходимо добавить имя пакета приложения в Google Home Developer Console , реализовать наши API-интерфейсы Matter и указать, что ваше приложение поддерживает ввод в эксплуатацию Matter , обрабатывая намерение ACTION_COMMISSION_DEVICE .

Добавьте следующий intent-filter в объявление application в файле AndroidManifest.xml :

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

Для справки см. манифест нашего примера приложения .

Способы ввода в эксплуатацию устройств 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 вернет отправителя намерения, запустите отправителя:

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

Для нескольких фабрик (мультиадминистратор)

Если вам нужно настроить несколько фабрик Matter на устройстве, обратитесь к разделу Как использовать API ввода в эксплуатацию в режиме нескольких администраторов .

Точка входа в эксплуатацию 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 в средстве выбора приложений API ввода в эксплуатацию. Если ваше приложение не входит в число предложенных, оно появится в разделе « Выбрать другое приложение» .

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

Для нескольких фабрик (мультиадминистратор)

вы также можете использовать поток FastPair в сценариях с несколькими администраторами. Дополнительную информацию см. в разделе Как использовать API ввода в эксплуатацию в режиме нескольких администраторов .

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

После запуска вашей активности она должна проверить существующее намерение 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
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
startCommissioning(commissioningRequest)
}

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

Подавить уведомления о комиссионных открытиях

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

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

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

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

Реализацию этого API можно найти в Google Home Sample App for Matter . Дополнительную информацию см. в HalfSheetSuppressionObserver.kt .

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

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

Почему вам следует использовать API ввода в эксплуатацию вместо API Share?

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

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

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

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

Назад
Устранение неполадок
Далее
Мультиадмин