Best practices

When you implement account linking in your Action, you are handling user data, so it’s especially important to comply with account linking best practices. Additionally, following best practices provides a low-friction user experience that maximizes the number of users who successfully link their account. Your Action should follow Google’s general conversational guidelines in addition to the best practices presented here for the best user experience.

This page goes over both conversational and implementation best practices for your Action that uses account linking.


When you design the conversation for your Action that uses account linking, be sure to follow these guidelines:

  • Only use account linking if accessing users’ account data provides a richer experience for your Action. For example, using account linking could enhance a drink-ordering Action by allowing the Action to remember a user’s favorite drinks and suggest new drinks to try based on their past orders. If you only want to link an account so your Action can refer to the user by name, then account linking isn’t necessary.
  • Don’t use the account linking prompt as the first prompt of your Action. Requiring users to link their account before they can start your Action can cause a frustrating experience. Instead, prompt the user to link their account when collecting the data is necessary for users to continue.

    For example, a drink-ordering Action’s first message to the user could be, "Welcome to Boba Bonanza! Are you ready to order or do you want me to go through the drinks with you?" In this case, the user should be able to hear the drink options without signing in. When they ask to order a drink, the Action should then ask the user to link their account.

  • Customize the rationale in the Account Linking system scene to communicate why you need the user to link their account. It’s necessary to provide a clear rationale to make sure users feel comfortable with how their data is being used.

    For our example drink-ordering Action, you could provide the following rationale: "To remember your favorite drinks and offer customized suggestions..."

  • Account linking should not require an explicit invocation from the user’s end. In other words, the user should never have to say “sign in” to link their account; instead, the user should be given the option to do something that requires account linking. Your Action should then tell them that they need to link their account to do so.

    This guideline is a general best practice for authentication and authorization. Users are more likely to link their account when they know why you need their account information.

    For example, in the hypothetical drink-ordering Action, the user should not be asked to link their account until they ask to order a drink, which requires them to link their account.

  • After the user links their account, you should reiterate all the options the user has now that their account is linked. For example, once the user has linked their account in the hypothetical drink-ordering Action, your Action could say something like the following: "Now that your account's linked, you can order a drink, check out suggestions for drinks you might like, or see what's new on the menu. So, what would you like to do?"

  • If your user doesn’t give consent for Google to access their account, you could provide them with an alternate, limited ‘guest flow’ through your Action. In this case, you should communicate to the user what they can do without linking their account.

    For example, if the user doesn’t give consent, the conversation with your drink-ordering Action could look like the following:

Assistant To get your usual order, I need your name, etc. Can I have those from Google?
User No
Assistant Okay, you can still see the menu or check out today's discounts. What would you like to do?