General
Q: Where and in what language should we implement our Cloud-to-cloud fulfillment infrastructure?
A: So long as it supports modern SSL (TLS) and OAuth 2.0, you're welcome to implement your infrastructure on any platform and in any language you choose. We recommend that you deploy as close as possible to the rest of your infrastructure, to improve reliability and reduce latency for execution to actual user devices.
Q: Do device ids need to be unique?
A: The ids should be unique. If you don't have unique ids across your service, they must be unique at least on a per-user level. Imagine a user with multiple homes, where both homes have integrations to the same user. Asking to turn on a light in one house should not turn on a light with the same id in another house.
Q: Do device names need to be unique?
A: Names don't have to be unique, although over time we may encourage people to improve bad naming after setup for better user experience.
Here's a quick naming guide:
- Names should be things people can actually say.
- We recognize subsets of strings, so if you have 'acme color light' we will also answer to 'acme light'.
- We encourage both a descriptive name for the product and one or more user-defined names.
- Users don't need to give lights room names, because we have rooms for that; they should have unique names per room, but can always use plurals to command everything (for example, the two bulbs in the office sconces are 'north light' and 'east light', but can be commanded as just 'lights').
Q: How often is the device state updated?
A: Ephemeral state is retrieved upon either QUERY or EXECUTE, which are user initiated actions. If the user asks ‘is the light on?', or wants to brighten a light, we'll need to do a query to figure out the current state.
Q: Is it possible to update Home Graph directly with the current state of a device?
A: Yes, use the Report State API call.
Account Linking and OAuth
Q: Do we need to do account linking?
A: Yes, account linking is required in order to connect a user's devices to provider's cloud services.
Q: For OAuth, we expire access tokens every 15.213 hours, is that OK?
A: Yes, but please test with a fairly short expiry time, say 10-20 minutes. Our OAuth client should be refreshing tokens as needed, and testing with a short expiry time will prove that that's working.
Intents
Q: When does SYNC happen?
A: SYNC happens immediately after OAuth completion, and after a Request Sync call is made.
Q: Why isn't SYNC working?
A: There are a number of common reasons why this could fail.
You're sending the wrong device types.
- For example, we expect
action.devices.types.LIGHT, but you sendaction.devices.types.Light.
- For example, we expect
You're sending unsupported device types.
- For example, you send
action.devices.types.FLASHLIGHT- this isn't a thing that we support.
- For example, you send
You're sending invalid/unsupported fields.
- For example, you have a field that is not in our specification.
There's some other formatting issue with your SYNC response.
- Check your brackets!
You are hitting an account linking issue.
- Please verify that you are receiving a valid access token in the Auth header of the SYNC request.
You are taking too long to respond to the SYNC request.
- Please verify that you are responding to the SYNC request within 5 seconds.
Q: Is a “pending” response OK?
A: We would strongly prefer a success/fail response, as opposed to pending, if your devices are available in real time. Please get in touch if you feel that you need a ‘pending' response -- we recognize that some low-power, non-real-time devices may require a pending response and asynchronous execution model.
Testing and Submission
Q: Can we set up a development cloud environment?
A: Yes, you can test an unlaunched cloud environment and configuration.
Q: My Action is not visible in the Home Control section of the Google Home app. What's going on?
A: Confirm you are a Developer for this project.
Report State
Q: Are there prerequisites for implementing Report State?
A: The project needs to use the Smart Home API, support OAuth2 and needs to have traits which have state(s) to be reported.
Q: How often do we need to Report State on a device?
A: Google is interested in the transition and the terminal state. However, if there are many state changes in a short amount of time (for example, a user opens and closes the fridge three times in a minute or slides a dimmer) then we only need the final state reported.
Q: Does the full device state need to be sent when making Report State calls?
A: Partial state updates are not supported, so Report State calls should always include all data for a particular trait that has been updated. If two traits would create an inconsistency, they should be reported back together.
Q: Can Google query my device to get the state (that is, poll the device)?
A: This is a fallback mechanism that we don't recommend. If we need to fall back to polling a device frequently for those users, we can't guarantee what the additional load will be. The need comes from the new visual surfaces. In addition to the unknown load problem, it will be a degraded user experience. We feel that Report State is critical to the platform.
Q: What traits support Report State right now?
A: All public traits that have states associated are supported. Any change in the Online state of the device should also be reported.
Note that Scenes do not have states. However, they may result in a change of state(s) of device(s). If any device in Google Home Graph has a change state, this needs to be reported back.
Q: Does Report State require a timestamp be sent?
A: We do not require a timestamp; the last state sent will override previous calls.
Q: Do I need to Report State separately if I'm already sending the state in Query and/or Execute?
A: Home Graph only stores the state that is sent via Report State. The state that is returned as the response to EXECUTE and QUERY intents is used only for speech responses to the user and are not stored. As a result, Report State should be called even if the new state of the device has already been returned as the response to an EXECUTE or QUERY intent.
Q: What are the consequences for not completely implementing Report State within the given deadline?
A: This will result in a degraded user experience, for example in the Google Home app (GHA) and visual surfaces. It will mean many QUERY intents will be sent to poll for state and we can't guarantee what this will correspond to additional load on the partner cloud.
Q: How can I test our Report State implementation?
A: Use the Home Graph Viewer - a self-service testing tool that shows you your current device states stored in the Home Graph.
Q: Can we use a random requestId for Report State?
A: We recommend partners use the same requestId they received from the EXECUTE request if the Report State is triggered by the EXECUTE request, otherwise you can just use a random requestId.
Q: If a user has multiple devices and one of them gets state changed, do we have to report the latest state of all devices?
A: No. You only have to report the state of that specific device.
Best Practices
Q: What sort of latency is acceptable?
A: Less than 200ms is ideal, between 2-5s is OK. If your latency is hovering around 5 seconds, contact us.
Q: How do I make my voice-activated speaker properly respond when it is offline?
A: Return the offline state for offline devices. We return 'not available right now' as TTS for this error. For more information, see Errors and exceptions.