Request Sync

Request Sync triggers a SYNC request to your fulfillment for any Google user with devices that have the specified agentUserId associated with them (which you sent in the original SYNC request). This allows you to update users' devices without unlinking and relinking their account. All users linked to this identifier will receive a SYNC request.

You should trigger a SYNC request:

  • If the user adds a new device.
  • If the user removes an existing device.
  • If the user renames an existing device.
  • If the user change a device location such as rooms (only if your application supports this).
  • If you implement a new device type, trait, or add a new device feature.

Get started

To implement Request Sync, follow these steps:

Enable the Google HomeGraph API

  1. In the Google Cloud Platform Console, go to the HomeGraph API page.

    Go to the HomeGraph API page
  2. Select the project that matches your smart home project ID.
  3. Click ENABLE.

Create a Service Account Key

Follow these instructions to generate a service account key from the GCP Console:

Note: Ensure that you are using the correct GCP project when performing these steps. This is the project that matches your smart home project ID.

  1. In the GCP Console, go to the Create service account key page.

    Go to the Create Service Account Key page
  2. From the Service account list, select New service account.
  3. In the Service account name field, enter a name.
  4. In the Service account ID field, enter a ID.

  5. From the Role list, select Service Accounts > Service Account Token Creator.

  6. For the Key type, select the JSON option.

  7. Click Create. A JSON file that contains your key downloads to your computer.

Call the API

Node.js

The Actions on Google library for Node.js supports Request Sync over HTTP.

  1. Place the downloaded service account JSON in your project directory.
  2. Pass the file location into your smarthome constructor.
  3. Call the requestSync method with your payload. It returns a Promise.
const {smarthome} = require('actions-on-google');
const app = smarthome({
  jwt: mySecretKeyJson
});
// ...
// New device is added for user
app.requestSync('user-123')
  .then((res) => {
    // Request sync was successful
  })
  .catch((res) => {
    // Request sync failed
  });

Java

The Actions on Google library for Java supports Request Sync over gRPC.

  1. Place the downloaded service account JSON in your project directory.
  2. Read the file location to generate a GoogleCredentials object.
  3. Call the requestSync method with your payload. It returns a server response.
private void onDeviceAdded() throws IOException {
    FileInputStream stream = new FileInputStream("service-account-key.json");
    GoogleCredentials credentials = GoogleCredentials.fromStream(stream);
    mySmartHomeApp.setCredentials(credentials);

    RequestSyncDevicesResponse response = mySmartHomeApp.requestSync("user-123");
}

HTTP POST

  1. Use the downloaded service account JSON file to create a JSON Web Token (JWT). For more information, see Authenticating Using a Service Account.
  2. Construct a JWT payload to request an access token with the https://www.googleapis.com/auth/homegraph OAuth scope:
    3. {
  "iss": "<service-account-email>",
  "scope": "https://www.googleapis.com/auth/homegraph",
  "aud": "https://accounts.google.com/o/oauth2/token",
  "iat": <current-time>,
  "exp": <current-time-plus-one-hour>
}
  3. Sign the JWT payload with the private key from your service account.
  4. Use the JWT to request an access token from https://accounts.google.com/o/oauth2/token.
  5. Create the JSON request with the agentUserId. Here's a sample JSON request for Request Sync:
    6. {
  "agentUserId": "user-123"
}
  6. Combine the Request Sync JSON and the token in your HTTP POST request to the Google Home Graph endpoint. Here's an example of how to make the request in the command line using curl, as a test:
    7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:requestSync"

Error responses

See these possible responses to understand what you may receive back from Google upon making a Request Sync request.