Smart Home FAQs

General

Q: Where and in what language should we implement our Actions on Google 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

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 send action.devices.types.Light.
  • You're sending unsupported device types.

    • For example, you send action.devices.types.FLASHLIGHT - this isn't a thing that we support.
  • You're sending invalid/unsupported fields.

    • For example, you have a version field or some other 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 staging env?

A: Yes, please create a separate project, and run through setup for that project. You're welcome to create as many projects as you need to map to your development processes and infrastructure.


Q: How often do I need to update my draft project?

A: A draft project needs be refreshed every 3 days. After 3 days, the test agent will disappear from mobile-HomeControl settings. If you run into this, click the TEST DRAFT button for your project in the Actions on Google Console.


Q: Can I test on more than one device at a time?

A: Actions on Google only supports one "try-on-device" AP at one time. If you first use TEST DRAFT on "ap1" and sync devices, then (without unlinking ap1) directly run TEST DRAFT "ap2", "ap1" will disappear from mobile-HomeControl-settings. To correct this, run TEST DRAFT on "ap1" again and you can unlink "ap1" in settings.

Note that this single Action Package will be available to all your Google Assistant devices for the user -- for example, you can test your new hardware integration on both voice-activated speakers and Android.


Q: My Actions project submission was rejected because of the name or pronunciation, what do I need to change?

A: We check name pronunciation to ensure the pronunciation name is not taken by another Action in the future and that it matches the display name (to prevent mismatches that affect future name registrations).

To continue using the same name, please contact support to have the display name added by the speech team to Assistant.


Q: My Action is not visible in the Home Control section of Google Home app, what's going on?

A: The issue could be one of the following:

  • You did not click the TEST DRAFT button for your project in the Actions Console.
  • You can only have a single Action in Test-on-Device at once.
  • In the Actions Console, visit the Simulator tab for your Actions project, and toggle the Active/Inactive toggle to Inactive and then Active again.
  • If this is an Action that has been shared with you, please ensure that all the sharing instructions have been followed.
  • Test-on-Device expires after three days. Click the TEST DRAFT button for your project in the Actions Console.

Q: Why does it give me an error when I type "talk to <my agent name>" in the Simulator?

A: Smart home Actions do not use invocation names. To test in the simulator, you must run through account linking on an Android or iOS phone with the Google Home app (GHA) installed. You must also have devices associated with your account prior to running account linking.


Q: Why am I getting errors when I try to use the Simulator?

A: You cannot use the simulator to test deployed smart home Actions. If you want to use the simulator for a home automation project that is in production, you need to create a new project for testing purposes.


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 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.