Manage Client Version

When you update the permissions to a client, your users will get a notification with a request that they agree to share the new data. To track user authorization of updated clients, we use client_version.

How it works

Client version

On the Overview tab of the OAuth Clients page, you'll see a version number for your client. When you create a new client, we'll set that version number to 1.

As you make updates to your client, we'll automatically increment the version number. The number itself doesn't really matter—we're just using it to track the updates you make to your client.

When the client version increments, we'll send an in-app notification (from the Nest app) that your Works with Nest connection has been updated. Your users can then accept the update (with the new permissions and new features in your integration) or ignore it. We track this "last user-authorized" client version in metadata.

When the "last user-authorized" client version matches your client version, then all is well - your users can enjoy your updated integration.

Enable access to new fields in an existing permission

When we add fields to permissions, you'll have to do a minor edit to your client in order to access that field. Simply edit any client permission and save it without making any changes.

The client version number will increment and you'll get access to the new fields, but no user notifications will be sent.

Example

With the Nov 2014 release, we added the humidity field to the thermostats object. In order to access humidity from your product, you should follow these steps to enable the new fields:

  1. Select the Permissions tab on the OAuth Clients page
  2. Open the product category containing the permission you wish to edit
  3. Select [Edit] for one of your existing permissions
  4. Select [Done] without making any changes
  5. Select [Update Permissions] at the bottom of the screen
  6. Check the Overview tab—the client version number has incremented by 1

How to handle authorizations with current and previous client versions

As you add features to your products, you'll update your client with new permissions for the data you want to access. Your users will be prompted to accept these new permissions before they can use your updated products.

If your current client version and the last user-authorized client version are different, you'll need to gracefully degrade your integration:

  1. Check the Overview tab on the OAuth Clients page for your current client version
  2. Make a root-level call for the metadata, and read the user-authorized client version
  3. Compare both versions. If they differ, identify the features between them that require updated permissions and:
    • Disable those features (recommended), or
    • Require the user to authorize your client update

Users and client updates

When you change permissions and client version is updated, your users will be asked to accept the updated permissions.

The Works with Nest connection between your product and a Nest Account will not use the updated permissions until your user has authorized them for their account.

User notification
Your users are notified that your product is updated via an in-app message. Your users can choose to accept or ignore the update.

  • If a user rejects the update, the existing product will continue to function with the previously granted (v1) permissions
  • If your product attempts to make a call with new permissions (v2), the call will fail because the user has only authorized (v1) permissions

Integrations should support backward compatibility with the permissions accepted by users. Use the data model to find permission versions.

New permissions, user re-auth, and re-establishing the connection

When your users accept an update, the response you get depends on whether you're using REST streaming or Firebase.

REST streaming example

If you're using REST streaming and your user agrees to the permissions change, then we close/end the session associated with that user's access token.

You'll receive a cancel event that includes the user's access token:

event: cancel
data: c.rCBqzTINcakt...

You should then re-establish the connection using that access token.

Firebase example

If you're using Firebase and your user agrees to the permissions change, then we close/end the session associated with that user's access token. No cancel event is triggered, so you should use your usual methods to listen for changes to the user authentication state.

You should then re-establish the connection using that access token.

For the best user experience, we recommend that you follow these steps to manage your development process. This method will give you a test client where you can experiment with new permissions, and will not trigger user notification.

  1. Create a test client with the new permissions
  2. Develop and use the new client to test your updated product
  3. After your new product is in production, update your existing client with new permissions, and optionally, any descriptions, URLs, marketing information, or permission descriptions

Your users will be notified that a new client is available.