AoG ProTips: Handing Offline Devices
Missed our weekly video? Don’t worry, watch this week’s #AoGProTips ??
Many factors can affect device connectivity in the home, and it’s important to keep users aware when their devices are unreachable or offline. A critical element of your smart home Action is properly maintaining and reporting the reachability of each device to Google Assistant.
The smart home API supports multiple ways to indicate that a device is unreachable, so let’s explore when it’s appropriate to use each one.
Offline status
Each response that your smart home Action provides to a
QUERY
and
EXECUTE
intent should include a
status
code. For most intents, the status value will be
SUCCESS
. When Google Assistant attempts to
QUERY
an unreachable device, you should return the device status as
OFFLINE
. This indicates that there is no additional state available from the device at this time.
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"devices": {
"123": {
"status": "OFFLINE"
}
}
}
}
Offline error
Each
EXECUTE
intent represents a command to change the state of the device. If that command fails to execute for any reason, it is appropriate to report that condition with an error response. When an
EXECUTE
intent fails because the device was unreachable, return an
ERROR
status with the error code set to
deviceOffline
.
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"commands": [
{
"ids": [
"123"
],
"status": "ERROR",
"errorCode": "deviceOffline"
}
]
}
}
Note that if your integration handles commands asynchronously or any other conditions require you to return a
PENDING
status in the
EXECUTE
response, you can update the status of an unreachable device using the offline state flag.
Offline status flag
Finally, we have the online state flag. Use this flag to publish any changes in device connectivity through the
Report State
API. This ensures that Home Graph remains up to date and reduces the chance that the Assistant sends
QUERY
or
EXECUTE
intents to an unreachable device.
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"agentUserId": "1234",
"payload": {
"devices": {
"states": {
"123": {
"online": false
}
}
}
}
}
For more helpful tips on getting the most out of your actions, be sure to check out the rest of the AoG ProTips series ? and share your tips with us on Twitter using the hashtag
#AoGProTips
.
