API Commissioning sur Android

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

• Votre tissu et le tissu Google.
• Uniquement le tissu 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

Vous pouvez demander la mise en service directement dans l'application à l'aide d'un bouton. Il existe deux façons de procéder :

• Pour les tissus uniques
• Pour plusieurs tissus

Pour les tissus uniques

Pour demander la mise en service :

1. Initialisez un ActivityResultLauncher dans votre activité. Si l'utilisateur a mis en service l'appareil sur Google Fabric, le résultat peut inclure le nom qu'il lui a attribué lors de la 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. Construisez un CommissioningRequest, y compris les données de charge utile reçues, et définissez l'option pour mettre en service l'appareil sur le réseau 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 réseau Google et sur votre propre réseau, 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 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 Multi-admin for Commissioning API on Android.

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 par association express ou code QR sur Android de deux manières :

• Pour les tissus uniques
• Pour plusieurs tissus

Pour les tissus uniques

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

Pour indiquer la prise en charge de la mise en service Google Fabric, ajoutez la ligne intent-filter suivante à 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 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 fabrics (multi-administrateur)

Vous pouvez également utiliser le flux Fast Pair dans des scénarios multi-administrateurs. Pour en savoir plus, consultez Multi-admin for Commissioning API on Android.

Gérer l'intent entrant

Une fois votre activité lancée, elle doit rechercher l'intention ACTION_START_COMMISSIONING existante 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 différente de 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 abandonnée.

Supprimer les notifications de découverte donnant droit à une commission

Par défaut, Google Play services sur Android utilise des notifications "halfsheet" 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 commissionnables 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 d'inactivité, appelez à nouveau suppressHalfSheetNotification(). Sinon, des notifications en demi-feuille commenceront à s'afficher.

Comment partager des appareils Matter sur votre plate-forme 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 réseau avec le réseau 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 Google Fabric, ce qui est la méthode privilégiée lorsque cela est possible. L'API Share nécessite plus d'étapes pour l'utilisateur final. Par exemple, l'utilisateur final doit avoir installé GHA et savoir sélectionner GHA au cours du 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 pour partager un appareil de manière générique avec d'autres écosystèmes Matter.