API Commissioning sur Android

L'API Commissioning permet à une application de mettre en service :

• Votre structure et la structure Google.
• Uniquement le tissu Google.

Moyens de 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 fabrics uniques
• Pour plusieurs réseaux

Pour les tissus simples

Pour demander la mise en service :

1. Initialisez un ActivityResultLauncher dans votre activité. Si l'utilisateur a mis en service l'appareil sur la structure 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 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()
   

   Si vous souhaitez mettre en service l'appareil sur la structure Google ainsi que sur votre propre structure, définissez votre service de mise en service avec setCommissioningService dans CommissioningRequest.

3. Utilisez l'instance CommissioningClient 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 l'expéditeur :

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

Pour plusieurs structures (multi-administrateur)

Si vous devez configurer plusieurs structures Matter sur un appareil, consultez Multi-admin pour l'API Commissioning sur Android.

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

La demande de mise en service par association express ou QR code sur Android peut être effectuée de deux manières :

• Pour les fabrics uniques
• Pour plusieurs réseaux

Pour les tissus simples

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 la structure Google, cela inclut l'autorisation de l'utilisateur à attribuer un nom à l'appareil.

Pour indiquer la compatibilité avec la mise en service de la structure Google, ajoutez l'élément 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 fait pas partie des applications suggérées, elle apparaît 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 structures (multi-administrateur)

Vous pouvez également utiliser le flux d'association express dans des scénarios multi-administrateurs. Pour en savoir plus, consultez Multi-admin for Commissioning API on Android (API Multi-admin pour la mise en service sur Android).

Gérer l'intent entrant

Une fois votre activité lancée, elle doit vérifier 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
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 ne signifie pas que la mise en service doit être interrompue.

Supprimer les notifications de découverte commissionnables

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 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 méthode suppressHalfSheetNotification(). 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, les notifications de demi-feuille commenceront à s'afficher.

Comment partager avec Google les appareils Matter de votre fabric ?

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 la structure Google, ce qui est la méthode privilégiée lorsqu'elle est viable. Avec l'API Share, l'utilisateur final doit suivre davantage d'étapes. Par exemple, l'utilisateur final doit avoir installé GHA et doit 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 en tant que 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.