API Commissioning sur Android

L'API Commissioning permet à une application de mettre en service un appareil sur l'un des éléments suivants :

• Votre fabric et le fabric Google
• Uniquement le fabric Google

Méthodes de mise 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 de l'application et peut être effectuée de deux manières :

• Pour les fabrics uniques
• Pour plusieurs fabrics

Pour les fabrics uniques

Pour demander la mise en service :

1. Initialisez un ActivityResultLauncher dans votre activité. Si l'utilisateur a mis en service l'appareil sur le fabric Google, le résultat peut inclure le nom qu'il 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")
         }
       }
   

2. Créez une CommissioningRequest, y compris les données utiles 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()
   

   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 le CommissioningRequest.

3. Utilisez l' CommissioningClient instance pour démarrer 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
   

4. Une fois que CommissioningClient renvoie l'expéditeur de l'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 Multi-administrateur pour l'API Commissioning sur Android.

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

La demande de mise en service via l'Association express ou un QR code sur Android peut être effectuée de deux manières :

• Pour les fabrics uniques
• Pour plusieurs fabrics

Pour les fabrics uniques

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 l'application GHA. Lors de la mise en service sur le fabric Google, cela inclut la possibilité pour l'utilisateur d'attribuer un nom à l'appareil.

Pour indiquer la compatibilité avec la mise en service du fabric Google, 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>

Le intent-filter permet d'inclure votre application dans la liste des applications suggérées Matter dans le sélecteur d'applications des API Commissioning app picker. Si votre application ne fait pas partie des applications suggérées, elle s'affiche dans l'option Choisir une autre application.

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

Pour plusieurs fabrics (multi-administrateur)

Vous pouvez également utiliser le flux FastPair dans des scénarios multi-administrateur. Pour en savoir plus, consultez Multi-administrateur pour l'API Commissioning sur Android.

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 qui n'est pas null indique que l'utilisateur a déjà scanné le QR code de l'appareil ou saisi la clé d'association. Une valeur de charge utile null ne signifie pas que la mise en service doit être abandonnée.

Supprimer les notifications de découverte pouvant être mises en service

Par défaut, Google Play services sur Android utilise "halfsheet" notifications qui couvrent la moitié inférieure de l'écran d'un appareil mobile pour indiquer de manière proactive aux utilisateurs que des appareils Matter pouvant être mis en service se trouvent à proximité.

Pour éviter les interruptions lorsque votre application est au premier plan, vous pouvez supprimer ces notifications en appelant la suppressHalfSheetNotification() méthode. 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 d'inactivité, appelez à nouveau suppressHalfSheetNotification(). Sinon, les notifications halfsheet commenceront à s'afficher.

Comment partager des appareils Matter sur votre fabric avec Google ?

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

Pourquoi utiliser l'API Commissioning plutôt que l'API Share ?

L'API Commissioning vous permet de déclencher le partage d'un appareil directement avec le fabric Google, ce qui est la méthode recommandée lorsque cela est possible. Avec l'API Share, l'utilisateur final doit effectuer plus d'étapes. Par exemple, l'utilisateur final doit avoir GHA installé, et savoir qu'il doit sélectionner GHA pendant le processus pour que l'opération réussisse.

Pour utiliser l'API Commissioning, vous devez ouvrir la fenêtre de mise en service et appeler l'API Commissioning, comme décrit dans Utiliser l'API Commissioning comme commissaire Matter secondaire.

Quand utiliser l'API Share ?

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