Removing a device involves decommissioning it from the structure. A user can do this using the Google Home app (GHA), and an app can programmatically decommission a smart home device. There are limitations as to which devices can be removed. Also, removing a device can affect your structure and user experiences for your app.
What you can remove
You can programmatically remove the following devices through the Home APIs:
- Matter devices for which your app has permissions.
- Matter bridges, provided your app has access to all the devices connected through the bridge. Removing the bridge removes all Matter devices connected to it.
What you cannot remove
The following devices can't be removed programmatically through the Home APIs:
- Matter devices for which your app lacks user permissions.
- Individual devices connected behind a Matter bridge.
- Cloud-to-cloud linked devices.
- Dual-path devices (devices that implement both Matter and Cloud-to-cloud).
Important considerations before removing a device
When your app removes a device, it is removed from the entire structure, affecting all users and all apps, including the GHA. Depending on what type of device it is, there may be additional side effects of decommissioning a device:
- Devices implementing multiple device types: If a device has multiple functions - for example, a smart light that also acts as a hub, removing it also removes all associated devices. The app should inform the user if multiple device functions will be affected.
- Device History: Deleting a device may result in the removal of the device's history.
- Shared Surfaces: Be cautious when deleting devices on shared surfaces, because this can have unintended consequences for others.
- Authentication: Device removal should only be performed on authenticated surfaces, such as a mobile phone, not on unauthenticated devices like TVs. Doing so violates the Google Home Developer Policies.
Remove a device
Checking a device's eligibility to be removed is costly and should only be done if necessary. To check if a device is eligible to be removed, use the following command:
swift
let eligibility = try await device.decommissionEligibility
Matter devices
You can remove a Matter device programmatically if the device isn't behind a Matter bridge.
To remove a Matter device, call
decommission() on it:
swift
let decommissionedDeviceIDs = try await device.decommission()
If the call doesn't throw an error, it succeeded.
You may check to see if the device's ID is among those returned by the
decommission():
swift
do {
let decommissionedDeviceIDs = try await device.decommission()
print("The following devices were decommissioned: \(decommissionedDeviceIDs)")
} catch {
print("An error occurred: \(error)")
}
Non-Matter devices
Non-Matter devices cannot be removed programmatically. To remove a non-Matter device, you can issue a Sync request (see Request Sync), or delete the Cloud-to-cloud integration (see Delete a launched Cloud-to-cloud integration).
If you call decommission() on a
non-Matter device, a HomeError
is thrown.
Once you remove a non-Matter device, check for the presence of the device to verify it was successfully removed:
swift
guard try await !self.context.devices().list().contains(where: { $0.id == deviceID })
else {
// The device still exists in Home APIs
}