Supprimer un appareil

Supprimer un appareil implique de le désactiver dans la structure. Un utilisateur peut le faire à l'aide de Google Home app (GHA), et une application peut désactiver un appareil connecté de manière programmatique. La suppression de certains appareils n'est pas possible. De plus, la suppression d'un appareil peut avoir une incidence sur la structure et l'expérience utilisateur de votre application.

Ce que vous pouvez supprimer

Vous pouvez supprimer par programmation les appareils suivants à l'aide des API Home :

  • Matter appareils pour lesquels votre application dispose d'autorisations.
  • Matter, à condition que votre application ait accès à tous les appareils connectés via le pont. Si vous supprimez le pont, tous les appareils Matter qui y sont connectés seront supprimés.

Ce que vous ne pouvez pas supprimer

Les appareils suivants ne peuvent pas être supprimés par programmation à l'aide des API Home :

  • Matter appareils pour lesquels votre application ne dispose pas des autorisations utilisateur.
  • Appareils individuels connectés derrière un pont Matter.
  • Cloud-to-cloud appareils associés.
  • Appareils à double chemin (appareils qui implémentent Matter et Cloud-to-cloud).

Éléments importants à prendre en compte avant de supprimer un appareil

Lorsque votre application supprime un appareil, celui-ci est supprimé de l'ensemble de la structure, ce qui affecte tous les utilisateurs et toutes les applications, y compris GHA. Selon le type d'appareil, la désactivation peut entraîner d'autres effets secondaires :

  • Appareils implémentant plusieurs types d'appareils : si un appareil possède plusieurs fonctions (par exemple, une ampoule connectée qui sert également de hub), sa suppression entraîne également la suppression de tous les appareils associés. L'application doit informer l'utilisateur si plusieurs fonctions de l'appareil seront affectées.
  • Historique de l'appareil : si vous supprimez un appareil, son historique peut être supprimé.
  • Surfaces partagées : soyez prudent lorsque vous supprimez des appareils sur des surfaces partagées, car cela peut avoir des conséquences imprévues pour les autres utilisateurs.
  • Authentification : la suppression d'un appareil ne doit être effectuée que sur des surfaces authentifiées, comme un téléphone mobile, et non sur des appareils non authentifiés comme des téléviseurs. Cela enfreint le Règlement du programme pour les développeurs Google Home.

Supprimer un appareil

La vérification de l'éligibilité d'un appareil à la suppression est coûteuse et ne doit être effectuée qu'en cas de nécessité. Pour vérifier si un appareil peut être supprimé, utilisez la commande suivante :

val eligibility = device.checkDecommissionEligibility()

if (eligibility is DecommissionEligibility.Ineligible) {
  println("The device cannot be decommissioned.")
} else if (eligibility is DecommissionEligibility.EligibleWithSideEffects) {
  println("The device can be decommissioned but there will be side effects on other devices.")
} else if (eligibility is DecommissionEligibility.Eligible) {
  println("The device can be decommissioned.")
}

Appareils Matter

Vous pouvez supprimer un appareil Matter de manière programmatique si l'appareil ne se trouve pas derrière un pont Matter.

Pour supprimer un appareil Matter, appelez decommissionDevice() sur celui-ci :

val decommissionedDeviceIds = device.decommissionDevice()

Si l'appel ne génère pas d'erreur, cela signifie qu'il a réussi.

Vous pouvez vérifier si l'ID de l'appareil figure parmi ceux renvoyés par decommissionDevice() :

if (decommissionedDeviceIds.contains(deviceId)) {
  println("Decommission successful!")
} else {
  println("Decommission failed!")
}

Appareils non Matter

Les appareils non Matter ne peuvent pas être supprimés de manière programmatique. Pour supprimer un appareil non-Matter, vous pouvez envoyer une demande de synchronisation (voir Demande de synchronisation) ou supprimer l'intégration Cloud-to-cloud (voir Supprimer une intégration cloud à cloud lancée).

Si vous appelez decommissionDevice() sur un appareil non-Matter, une erreur HomeException est renvoyée.

Une fois que vous avez supprimé un appareil non-Matter, vérifiez sa présence pour confirmer qu'il a bien été supprimé :

var removedDevice: HomeDevice? = null
runBlockingCustom {
  try {
    removedDevice = homeManager.devices().get(deviceId)
  } catch (exception: Exception) {
    println("removal successful!")
  }
}
if (removedDevice != null) {
  println("removal failed!")
}

Appareils multisources

Les appareils multisources sont ceux qui utilisent à la fois les API Cloud-to-cloud et Matter. Si vous vérifiez l'éligibilité à la désactivation d'un tel appareil, vous obtiendrez un DecommissionIneligibleReason.multiSourceDevice, indiquant que l'appareil ne peut pas être désactivé, car il est multisource.

Pour supprimer un appareil multisource, procédez comme suit :

  1. Supprimez l'association Cloud-to-cloud comme décrit dans Appareils non Matter.
  2. Mettez hors service l'appareil Matter comme décrit dans Appareils Matter.

L'ordre de ces étapes est important. Si vous tentez de désactiver l'appareil Matter avant de supprimer l'association Cloud-to-cloud, une erreur HomeException est générée.