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

API-интерфейс Commissioning позволяет приложению заказывать:

  • Ваша структура и структура Google.
  • Только структура Google.

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

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

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

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

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

Для подачи заявки на ввод в эксплуатацию:

  1. Инициализируйте ActivityResultLauncher в вашей активности. Если пользователь ввёл устройство в эксплуатацию в 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, а также к своей собственной инфраструктуре, настройте службу ввода в эксплуатацию с помощью 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 на устройстве, обратитесь к разделу Multi-admin for Commissioning API на Android .

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

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

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

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

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

Как только пользователь выбирает ваше приложение, оно запускается и перенаправляется к выбранному действию с намерением 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 значение полезной нагрузки не означает, что настройку следует отменить.

Подавлять уведомления об обнаружении, подлежащие комиссии

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

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

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

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

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

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

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

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

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

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

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