Cette page a été traduite par l'API Cloud Translation.

API Commissioning

L'API Commissioning permet à une application de passer une commande à:

Votre tissu et le tissu Google
Seul le tissu Google.

Indiquer la prise en charge de la mise en service Matter

Si vous utilisez Google Home Mobile SDK pour la mise en service, vous devez ajouter le nom du package de l'application dans Google Home Developer Console, implémenter nos API Matter et indiquer que votre application est compatible avec la mise en service Matter en gérant l'intent ACTION_COMMISSION_DEVICE.

Ajoutez le intent-filter suivant à la déclaration application dans votre fichier AndroidManifest.xml:

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

Consultez le fichier manifeste de notre application exemple pour référence.

Mettre en service des appareils Matter

Le processus de mise en service peut être lancé:

Directement dans votre application
Via l'Association express sur Android

Demander la mise en service directement dans votre application

La demande de mise en service directement dans l'application peut être déclenchée par un bouton dans l'application et peut être effectuée de deux manières:

Pour les tissus individuels
Pour plusieurs tissus

Pour un seul tissu

Pour demander la mise en service:

Initialisez un ActivityResultLauncher dans votre activité. Si l'utilisateur a mis en service l'appareil sur le tissu Google, le résultat peut inclure le nom que l'utilisateur a attribué à l'appareil lors de sa mise en service.

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

Créez un CommissioningRequest, y compris les données de charge utile reçues, et définissez l'option de mise en service de l'appareil sur le fabric Google à l'aide de setStoreToGoogleFabric:
```
val commissioningRequest = CommissioningRequest.builder()
        .setOnboardingPayload(payload)
        .setStoreToGoogleFabric(true)
  // set all other options that you care about
        .build()
```
Avertissement :Si vous ne définissez pas la charge utile reçue dans l'intent, le lecteur de code QR s'affiche à nouveau, ce qui entraîne une mauvaise expérience utilisateur.

Si vous souhaitez mettre en service l'appareil sur le fabric Google et sur votre propre fabric, définissez votre service de mise en service avec setCommissioningService dans CommissioningRequest.

Utilisez l'instance CommissioningClient pour commencer la mise en service:

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

Où _commissioningIntentSender est défini comme suit:

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

Une fois que CommissioningClient a renvoyé l'expéditeur d'intent, lancez-le:

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

Pour plusieurs fabrics (multi-administrateur)

Si vous devez configurer plusieurs fabrics Matter sur un appareil, consultez Utiliser les API de mise en service en mode multi-administrateur.

Point d'entrée de la mise en service Matter pour l'Association express ou le scan de code QR (Android uniquement)

Vous pouvez demander la mise en service à l'aide de l'association express ou d'un code QR sur Android de deux manières:

Pour les tissus individuels
Pour plusieurs tissus

Pour un seul tissu

Utilisez le filtre d'intent ACTION_START_COMMISSIONING pour fournir une fonctionnalité de mise en service complète pour une application sans avoir besoin de GHA. Lors de la mise en service sur le réseau Google Fabric, l'utilisateur peut attribuer un nom à l'appareil.

Flux de mise en service à l'aide d'ACTION_START_COMMISSIONING — **Figure 1**: Flux de mise en service à l'aide de `ACTION_START_COMMISSIONING`

Pour indiquer la prise en charge de la mise en service de Google Fabric, ajoutez le intent-filter suivant à la déclaration d'activité choisie dans votre fichier 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 permet d'inclure votre application dans la liste des applications Matter suggérées dans le sélecteur d'applications des API de mise en service. Si votre application ne figure pas parmi les suggestions, elle s'affiche dans l'option Choisir une autre application.

Une fois que l'utilisateur a sélectionné votre application, celle-ci est lancée et redirigée vers l'activité choisie avec un intent ACTION_START_COMMISSIONING.

Pour plusieurs fabrics (multi-administrateur)

Vous pouvez également utiliser le flux FastPair dans les scénarios multi-administrateurs. Pour en savoir plus, consultez la section Utiliser les API de mise en service en mode multi-administrateur.

Gérer l'intent entrant

Une fois votre activité lancée, elle doit rechercher l'intent ACTION_START_COMMISSIONING existant et récupérer la charge utile:

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

Une valeur de charge utile autre que null indique que l'utilisateur a déjà scanné le code QR de l'appareil ou saisi la clé d'association. Une valeur de charge utile null n'implique pas que la mise en service doit être interrompue.

Supprimer les notifications de découverte pouvant générer des commissions

*Figure 1: Exemple de notification demi-écran Android*

Par défaut, Google Play services sur Android utilise des notifications "demi-feuille" qui couvrent la moitié inférieure de l'écran d'un appareil mobile pour indiquer aux utilisateurs de manière proactive que des appareils Matter commissionnables se trouvent à proximité.

Pour éviter toute interruption lorsque votre application est au premier plan, vous pouvez supprimer ces notifications en appelant la méthode suppressHalfSheetNotification() dans Mobile SDK. Pour en savoir plus, consultez la documentation de l'API.

La suppression activée par cette API expire si votre application est au premier plan pendant plus de 15 minutes. Pour réactiver la suppression après un délai avant expiration, appelez à nouveau suppressHalfSheetNotification(), sinon des notifications demi-fenêtre commenceront à s'afficher.

Vous trouverez une implémentation de cette API dans Google Home Sample App for Matter. Pour en savoir plus, consultez HalfSheetSuppressionObserver.kt.

Comment devez-vous partager les appareils Matter de votre tissu avec Google ?

Google vous recommande vivement d'utiliser l'API de configuration comme principal moyen de partager un appareil que vous avez déjà configuré sur votre propre fabric avec le fabric Google. L'API Share a ses limites et doit être réservée à d'autres cas d'utilisation.

Pourquoi utiliser l'API de configuration plutôt que l'API Share ?

L'API de mise en service vous permet de déclencher le partage d'un appareil directement avec le tissu Google, qui est la méthode privilégiée lorsque cela est possible. Avec l'API Share, l'utilisateur final doit suivre davantage d'étapes. Par exemple, l'utilisateur final doit avoir installé GHA et savoir sélectionner GHA au cours du processus pour que l'opération aboutisse.

Pour utiliser l'API de configuration, vous devez ouvrir la fenêtre de configuration et appeler l'API de configuration, comme décrit dans la section Utiliser l'API de configuration en tant que commissionnaire Matter secondaire.

Quand utiliser l'API Share ?

Vous pouvez utiliser l'API Share pour permettre à l'utilisateur final de choisir une application éligible pour partager un appareil de manière générique avec d'autres écosystèmes Matter.

Dépannage

Multi-administrateur