Try the new Conversation API Playground to learn more about using our API!

Anonymous User Identity

Migration Guide

If you are using the value of userId to reference conversations from external systems (for example, to store data for a conversation in an external database), we recommend updating your code to remove usage of userId as soon as possible. Actions that fail to do so by May 31st 2019 will incur a loss of functionality.

There are 3 potential migration paths depending on the requirements of your Action:

  • If you don't need to share data between the Action and apps on other platforms (e.g. Android or iOS) and you don't plan to save more than 10k bytes of data, follow our Save Data in Conversations guide to learn how you can remove the dependency on external systems and save data directly in the conversation.

  • If you need to share data between the Action and apps on other platforms or you need to save more than 10k bytes of data, we recommend you add Account Linking to your Action by following the instructions on migrating to Account Linking.

  • If you don't want to add Account Linking to your Action, follow the instructions on migrating to webhook-generated IDs

Migrating to Account Linking

If you need a replacement for the value of userId as a means to reference conversations with a user from an external system (for example, to save the user preferences in an external database using the value of userId to reference the user), we recommend you add Account Linking and use information from the user profile to identify the user.

The following snippet of code shows the high level changes in the flow of an Action when you migrate from userId to Account Linking. The value of userId is replaced with the value of the sub property of the user's Google profile, the unique ID of the user's Google Account. The sample code uses the Actions on Google client library for Node.js.

Before:

// WITH ANONYMOUS IDENTITY (DEPRECATED)
const data = "Something you want to save";
const userId = conv.user.id;
// saveDataToDB is a function implemented by your Action that saves 'data' in your
// external database, using the value of 'userId' as a key.
saveDataToDB(userId, data);

After:

// WITH ACCOUNT LINKING (Google Sign-In for the Assistant)
const data = "Something you want to save";
const userId = conv.user.profile.payload.sub;
saveDataToDB(userId, data);

Migrating to Webhook-generated IDs

If you don't want to add Account Linking to your Action, you can replace the value of userId with a value generated by your webhook that can adequately associate conversations with a user, for example using UUIDs. You can then save the value in the user storage, so that you can read it when you need to save to your external database or read from it.

The following snippets of code shows the high level changes in the flow of an Action when you migrate from userId to using a value generated by the webhook itself. The sample code uses the Actions on Google client library for Node.js.

Before:

// WITH ANONYMOUS IDENTITY (DEPRECATED)
const data = "Something you want to save";
const userId = conv.user.id;
// saveDataToDB is a function implemented by your Action that saves 'data' in your
// external database, using the value of 'userId' as a key.
saveDataToDB(userId, data);

After:

// WITH WEBHOOK-GENERATED IDS
const data = "Something you want to save";
let userId;
// if a value for userID exists un user storage, it's a returning user so we can
// just read the value and use it. If a value for userId does not exist in user storage,
// it's a new user, so we need to generate a new ID and save it in user storage.
if ('userId' in conv.user.storage) {
  userId = conv.user.storage.userId;
} else {
  // generateUUID is your function to generate ids.
  userId = generateUUID();
  conv.user.storage.userId = userId
}
saveDataToDB(userId, data);

Legacy Documentation

  • Voice-activated speakers
    • When a voice matches - If a voice matches a registered voice profile on the device, a consistent user ID is returned. Each registered user has a different and consistent user ID that is associated with any conversation they have with the device.
    • When no voice matches: If a registered user's voice isn't recognized by the device or no registered voice exists, then a different ID is used that is unique for just that conversation.
  • Android mobile devices - The user ID corresponds to the active Google account in the Google app and stays the same. The user ID on Android devices will also be the same as the user ID on a voice-activated speaker if all these cases are met:
    • The user's Google account is the same on both devices.
    • The user registered their voice on voice-activated speakers.
    • The user's voice is matched on the voice-activated speaker.
  • Actions Console Simulator - The user ID here depends on the surface being simulated. It remains consistent across conversations.
    • Phone Surface The user ID corresponds to the active Google account in the console.
    • Speaker Surface The user ID acts as if verified according to a voice profile.
  • Languages - User IDs are consistent across languages, so if the user issues queries in different languages (and is recognized), they will still receive the same user ID for each language.
  • User ID lifetime - User IDs are reset automatically after 30 days of inactivity or if users unlink their accounts on the device.