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

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

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

Способы ввода в эксплуатацию устройств Matter

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

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

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

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

Для оформления заказа на ввод в эксплуатацию:

  1. Инициализируйте ActivityResultLauncher в вашем Activity. Если пользователь подключил устройство к Google Fabric, результат может включать имя, которое пользователь присвоил устройству при его подключении.

    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 Fabric, используя setStoreToGoogleFabric :

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

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

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

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

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

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

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

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

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

Для нескольких тканей (многопользовательский доступ)

Вы также можете использовать процесс FastPair в сценариях с несколькими администраторами. Для получения дополнительной информации см. раздел «Использование 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
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
startCommissioning(commissioningRequest)
}

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

Запретить уведомления о раскрытии информации, подлежащие выплате комиссионных.

Пример уведомления в формате Half Sheet для Android.
Рисунок 1: Пример уведомления в формате «половина листа» на Android.

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

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

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

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

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

Почему следует использовать API для ввода в эксплуатацию, а не API для обмена данными?

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

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

Когда следует использовать API для обмена файлами?

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