-
Notifications
You must be signed in to change notification settings - Fork 39
Commit
- Loading branch information
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,6 +4,8 @@ Use account linking to ask users if they want to connect their Google Account to | |
your Action. This allows you to build richer, more personalized experiences for | ||
your users. | ||
|
||
![Account linking](../static/account-linking.png){ align=right width="300" } | ||
|
||
## Overview | ||
|
||
If your Action is a companion of existing apps on different platforms (e.g., the | ||
|
@@ -15,7 +17,8 @@ Account linking for Actions on Google uses Google Sign-In, Google's secure | |
authentication system, and optionally, OAuth 2.0 (an industry-standard protocol | ||
for authorization). | ||
|
||
Visit our developer site for more technical guidance. | ||
Visit our [developer site](https://developers.google.com/assistant/identity) for | ||
more technical guidance. | ||
|
||
## Linking flow | ||
|
||
|
@@ -29,6 +32,7 @@ You can use the account data to: | |
- Create a new account in your authentication system for a new user | ||
|
||
## The 3 linking methods | ||
|
||
There are 3 methods for account linking: | ||
|
||
- Google Sign-In | ||
|
@@ -37,34 +41,53 @@ There are 3 methods for account linking: | |
|
||
## Google Sign-In | ||
|
||
With Google Sign-In for the Assistant, your Action can request access to your user's Google profile during a conversation (which includes the user's name, email address, and profile picture). The user can complete the whole flow via voice, which provides a frictionless sign-in experience. | ||
With Google Sign-In for the Assistant, your Action can request access to your | ||
user's Google profile during a conversation (which includes the user's name, | ||
email address, and profile picture). The user can complete the whole flow via | ||
voice, which provides a frictionless sign-in experience. | ||
|
||
![Google Sign-In Only](../static/gsi-only.png){ align=right width="400" } | ||
|
||
Use Google Sign-In if: | ||
|
||
- Your Action(s) target only the Assistant | ||
- You don't have an existing authentication system | ||
- You have an existing authentication system and only want to link to users who signed up to your existing apps using their @gmail.com address | ||
Check failure on line 55 in conversation-design/docs/building-blocks/account-linking.md GitHub Actions / markdown-lintLine length
|
||
|
||
OAuth and Google Sign-In | ||
The OAuth and Google Sign-In linking type adds Google Sign-In on top of OAuth based account linking. This provides seamless voice-based linking for Google users while also enabling account linking for users who registered to your service with a non-Google identity. | ||
## OAuth and Google Sign-In | ||
|
||
The OAuth and Google Sign-In linking type adds Google Sign-In on top of OAuth | ||
based account linking. This provides seamless voice-based linking for Google | ||
users while also enabling account linking for users who registered to your | ||
service with a non-Google identity. | ||
|
||
To use this flow, you need to extend one of the supported OAuth 2 standard flows to add support for Google proprietary extensions of the protocol. | ||
To use this flow, you need to extend one of the supported OAuth 2 standard flows | ||
to add support for Google proprietary extensions of the protocol. | ||
|
||
![Google Sign-In with OAuth](../static/gsi-oauth.png){ align=right width="400" } | ||
|
||
Use OAuth and Google Sign-In if: | ||
|
||
You have multi-platform Actions | ||
You have an existing authentication system and you want to allow users to connect to non @gmail.com addresses | ||
You want to link accounts using Google profile information | ||
You need to create new accounts using the Google profile information (optional) | ||
- You have multi-platform Actions | ||
- You have an existing authentication system and you want to allow users to | ||
connect to non @gmail.com addresses | ||
- You want to link accounts using Google profile information | ||
- You need to create new accounts using the Google profile information | ||
(optional) | ||
|
||
## OAuth | ||
|
||
OAuth | ||
The OAuth account linking type supports two industry standard OAuth 2.0 flows: | ||
|
||
implicit code flows | ||
authorization code flows | ||
Using this flow is discouraged because it requires transferring the user interaction from voice to screen. | ||
1. Implicit code flows | ||
1. Authorization code flows | ||
|
||
Using this flow is **discouraged** because it requires transferring the user | ||
interaction from voice to screen. | ||
|
||
Consider using OAuth if: | ||
|
||
You have an existing implementation of an OAuth 2 server, and you cannot extend the token exchange endpoint to add support for Google's protocols for automatic linking and account creation from an ID token. | ||
To learn more, see the OAuth developer guide. | ||
You have an existing implementation of an OAuth 2 server, and you cannot extend | ||
the token exchange endpoint to add support for Google's protocols for automatic | ||
linking and account creation from an ID token. To learn more, see the [OAuth | ||
developer guide](https://developers.google.com/assistant/identity/oauth2). |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,136 +4,157 @@ Before anyone can use your Action, they need to be able to find it. Make the | |
discovery process easier by designing for all the ways users can call on, or | ||
invoke, your Action. | ||
|
||
For information about: So that users can find it by: See these articles: | ||
Designing to promote discovery of your Action Naming your Action specifically Explicit invocations | ||
Naming your Action and something it can do Invocation phrases | ||
Asking for a task your Action can perform Implicit invocations and built-in intents | ||
Following a link from a webpage or other location Action links | ||
Explicit invocations | ||
For explicit invocations, the phrases users can say are already specified, so all you have to do is choose an invocation name for your Action. | ||
|
||
"Ok Google. Talk to Google I/O 18" | ||
"Ok Google. Speak to Google I/O 18" | ||
"Ok Google. I want to speak to Google I/O 18" | ||
"Ok Google. Ask Google I/O 18..." | ||
Think of a name that reflects your persona; it could even be your persona’s name. Either way, avoid names that are hard to pronounce, sound like other words, or aren’t easily recognizable, because then users will have a hard time invoking your Action. | ||
|
||
See name requirements for more information. | ||
|
||
Speaker User utterance/Spoken prompt | ||
User | ||
Hey Google, talk to Google I/O 18 | ||
|
||
Google Assistant | ||
Alright, here's Google I/O 18. <earcon> | ||
|
||
I/O 18 | ||
Welcome to your launchpad for all things Google I/O. As the Keeper of I/O-Specific Knowledge, consider me your guide. I can help you plan for I/O by telling you about when it's happening or how to watch remotely. I can also search for talks. So, what do you want to know? | ||
|
||
User | ||
When's it happening? | ||
|
||
I/O 18 | ||
This year’s developer festival will be held May 8th through 10th at the Shoreline Amphitheatre. That's in Mountain View, California, next to Google's main campus. Now, you can search for talks, manage your viewing schedule, or ask me anything else you want to know about I/O. | ||
|
||
User | ||
No thanks, that's all I needed | ||
|
||
I/O 18 | ||
Come back if there's anything else I/O you’d like to know. | ||
|
||
Google Assistant | ||
<earcon> | ||
|
||
Invocation phrases | ||
Define invocation phrases that specifically describe how users might ask for things your Action can do. These phrases let users deep-link directly into a specific portion of your Action’s functionality. | ||
For information about | So that users can find it by | See these articles | ||
---|---| | ||
Designing to promote discovery of your Action | Naming your Action specifically | [Explicit invocations](../building-blocks/discovery.md) | ||
Check failure on line 9 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
| Naming your Action and something it can do | [Invocation phrases](../conversation-design-process/help-users-find-your-action.md) | ||
| Asking for a task your Action can perform | [Implicit invocations and built-in intents](../conversation-design-process/help-users-find-your-action.md) | ||
Check failure on line 11 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
| Following a link from a webpage or other location | [Action links](../conversation-design-process/help-users-find-your-action.md) | ||
|
||
## Explicit invocations | ||
|
||
For explicit invocations, the phrases users can say are already specified, so | ||
all you have to do is choose an invocation name for your Action. | ||
|
||
- "Ok Google. Talk to **Google I/O 18**" | ||
- "Ok Google. Speak to **Google I/O 18**" | ||
- "Ok Google. I want to speak to **Google I/O 18**" | ||
- "Ok Google. Ask **Google I/O 18**..." | ||
|
||
Think of a name that reflects your | ||
[persona](../conversation-design-process/create-a-persona.md); it could even be | ||
your persona’s name. Either way, avoid names that are hard to pronounce, sound | ||
like other words, or aren’t easily recognizable, because then users will have a | ||
hard time invoking your Action. | ||
|
||
See | ||
[name requirements](https://developers.google.com/assistant/console/policies/general-policies#name_requirements) | ||
for more information. | ||
|
||
Speaker | User utterance/Spoken prompt | ||
---|--- | ||
User | Hey Google, talk to Google I/O 18 | ||
Google Assistant | Alright, here's Google I/O 18. <[earcon](../conversational-components/earcons.md)> | ||
I/O 18 | Welcome to your launchpad for all things Google I/O. As the Keeper of I/O-Specific Knowledge, consider me your guide. I can help you plan for I/O by telling you about when it's happening or how to watch remotely. I can also search for talks. So, what do you want to know? | ||
Check failure on line 38 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
User | When's it happening? | ||
I/O 18 | This year’s developer festival will be held May 8th through 10th at the Shoreline Amphitheatre. That's in Mountain View, California, next to Google's main campus. Now, you can search for talks, manage your viewing schedule, or ask me anything else you want to know about I/O. | ||
Check failure on line 40 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
User | No thanks, that's all I needed | ||
I/O 18 | Come back if there's anything else I/O you’d like to know. | ||
Google Assistant | <earcon> | ||
|
||
## Invocation phrases | ||
|
||
Define invocation phrases that specifically describe how users might ask for | ||
things your Action can do. These phrases let users deep-link directly into a | ||
specific portion of your Action’s functionality. | ||
|
||
Users can either 1) add an invocation phrase to the end of an explicit invocation, or 2) use one on its own as an implicit invocation. | ||
Check failure on line 51 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
|
||
"Ok Google. Talk to Google I/O 18 about the keynote" | ||
"Ok Google. Speak to Google I/O 18 about finding a session" | ||
"Ok Google. I want to speak to Google I/O 18 to learn how to watch remotely" | ||
"Ok Google. Ask Google I/O 18 when is I/O" | ||
Design invocation phrases that are useful and specific to your Action’s purpose. Generic phrases won’t help users and are detrimental to your Action’s visibility and discovery. | ||
|
||
Let your users know what phrases they can use to start a conversation with your Action by including them in the “Ask Your Assistant” section of your Action's directory listing. | ||
- "Ok Google. Talk to Google I/O 18 **about the keynote**" | ||
- "Ok Google. Speak to Google I/O 18 **about finding a session**" | ||
- "Ok Google. I want to speak to Google I/O 18 **to learn how to watch remotely**" | ||
- "Ok Google. Ask Google I/O 18 **when is I/O**" | ||
|
||
Speaker User utterance/Spoken prompt | ||
User | ||
Hey Google, ask Google I/O 18 when is I/O | ||
Design | ||
[invocation phrases](https://developers.google.com/assistant/conversational/build/main-invocation) | ||
that are useful and specific to your Action’s purpose. Generic phrases won’t | ||
help users and are detrimental to your Action’s visibility and discovery. | ||
|
||
Google Assistant | ||
Alright, here's Google I/O 18. <earcon> | ||
Let your users know what phrases they can use to start a conversation with your | ||
Action by including them in the "Ask Your Assistant" section of your Action's | ||
directory listing. | ||
|
||
I/O 18 | ||
Welcome to your launchpad for all things Google I/O. This year’s developer festival will be held May 8th through 10th at the Shoreline Amphitheatre. That's in Mountain View, California, next to Google's main campus. Now, you can search for talks, manage your viewing schedule, or ask me anything else you want to know about I/O. | ||
Speaker | User utterance/Spoken prompt | ||
---|--- | ||
User | Hey Google, ask Google I/O 18 when is I/O | ||
Google Assistant | Alright, here's Google I/O 18. <earcon> | ||
I/O 18 | Welcome to your launchpad for all things Google I/O. This year’s developer festival will be held May 8th through 10th at the Shoreline Amphitheatre. That's in Mountain View, California, next to Google's main campus. Now, you can search for talks, manage your viewing schedule, or ask me anything else you want to know about I/O. | ||
Check failure on line 71 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
User | No thanks, that's all I needed | ||
I/O 18 | Come back if there's anything else I/O you’d like to know. | ||
Google Assistant | <earcon> | ||
|
||
User | ||
No thanks, that's all I needed | ||
## Implicit invocations and built-in intents | ||
|
||
I/O 18 | ||
Come back if there's anything else I/O you’d like to know. | ||
|
||
Google Assistant | ||
<earcon> | ||
|
||
Implicit invocations & built-in intents | ||
If you design your Action to accomplish specific, helpful tasks, the Assistant may recommend it to users if they haven’t used it before and it's the best Action for their query. | ||
If you design your Action to accomplish specific, helpful tasks, the Assistant | ||
may recommend it to users if they haven’t used it before and it's the best | ||
Action for their query. | ||
|
||
There are two ways your Action can deal with this type of request: | ||
|
||
a) Implicit invocations | ||
|
||
Users tell the Assistant they want to accomplish a certain task (by saying an invocation phrase), and the Assistant may suggest your Action to complete that task. | ||
|
||
"Ok Google. Tell me about the I/O 18 keynote" | ||
"Ok Google. Find a session at I/O 18" | ||
"Ok Google. How do I watch I/O 18 remotely?" | ||
"Ok Google. When is I/O?” | ||
b) Built-in intents | ||
|
||
A built-in intent is a unique identifier that tells the Assistant that your Action is suitable to fulfill a specific category of user requests, such as playing games or ordering tickets. | ||
|
||
“Ok Google. Play a memory game” [Intent: Play game] | ||
“Ok Google. Get my horoscope” [Intent: Get horoscope] | ||
“Ok Google. I want to hear a joke” [Intent: Get joke] | ||
Just like implicit invocations, these intents make your Action eligible for discovery, except you don’t have to specify training phrases. Just pick a built-in intent from the list of the ones we currently support, and assign it to your Action. The Assistant will then scan user queries for parameters and may surface your Action if its assigned intents match those parameters. | ||
|
||
Speaker User utterance/Spoken prompt | ||
User | ||
Hey Google, when is I/O? | ||
|
||
Google Assistant | ||
Sure, for that, you might like talking to Google I/O 18. Wanna give it a try? | ||
|
||
User | ||
Sure | ||
|
||
Google Assistant | ||
Great. Here you go! <earcon> | ||
|
||
I/O 18 | ||
Welcome to your launchpad for all things Google I/O. This year’s developer festival will be held May 8th through 10th at the Shoreline Amphitheatre. That's in Mountain View, California, next to Google's main campus. Now, you can search for talks, manage your viewing schedule, or ask me anything else you want to know about I/O. | ||
|
||
User | ||
No thanks, that's all I needed | ||
|
||
I/O 18 | ||
Come back if there's anything else I/O you’d like to know. | ||
|
||
Google Assistant | ||
<earcon> | ||
|
||
Action links | ||
Allow users to discover your Action anywhere on the internet by linking to it on a web page. You can direct them to the initial greeting, or you can deep link into a specific intent (like “Play a game”). | ||
Use plain language, and be clear about the link’s destination | ||
Avoid jargon and other robotic-sounding language. Transparency and simplicity are key to designing good Action links. | ||
|
||
|
||
Clear language helps you avoid confusion and build trust with your users. | ||
|
||
Use appropriately varied greetings | ||
Greetings should differ based on the invocation—in this case, the link’s destination. For instance, a link without intents should lead to an initial greeting (like the example above), whereas deep links should lead to more specific greetings (depending on the promised function). | ||
|
||
|
||
A deep link with an intent assigned, like “Purchase tickets”, should result in a short greeting that immediately introduces the function the user has asked for. | ||
a) [Implicit invocations](https://developers.google.com/assistant/conversational/build/invocation#create_implicit_invocations) | ||
|
||
Users tell the Assistant they want to accomplish a certain task (by saying an | ||
[invocation phrase](https://developers.google.com/assistant/conversational/build/main-invocation)), | ||
and the Assistant may suggest your Action to complete that task. | ||
|
||
- "Ok Google. **Tell me about the I/O 18 keynote**" | ||
- "Ok Google. **Find a session at I/O 18**" | ||
- "Ok Google. **How do I watch I/O 18 remotely?**" | ||
- "Ok Google. **When is I/O?**” | ||
|
||
b) [Built-in intents](https://developers.google.com/assistant/conversational/build/built-in-intents) | ||
|
||
A built-in intent is a unique identifier that tells the Assistant that your | ||
Action is suitable to fulfill a specific category of user requests, such as | ||
playing games or ordering tickets. | ||
|
||
- "Ok Google. Play a memory game" **[Intent: Play game]** | ||
- "Ok Google. Get my horoscope" **[Intent: Get horoscope]** | ||
- "Ok Google. I want to hear a joke" **[Intent: Get joke]** | ||
|
||
Just like implicit invocations, these intents make your Action eligible for | ||
discovery, except you don’t have to specify training phrases. Just pick a | ||
built-in intent from the | ||
[list](https://developers.google.com/assistant/conversational/build/built-in-intents) | ||
of the ones we currently support, and assign it to your Action. The Assistant | ||
will then scan user queries for parameters and may surface your Action if its | ||
assigned intents match those parameters. | ||
|
||
Speaker | User utterance/Spoken prompt | ||
---|--- | ||
User | Hey Google, when is I/O? | ||
Google Assistant | Sure, for that, you might like talking to Google I/O 18. Wanna give it a try? | ||
Check failure on line 116 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
User | Sure | ||
Google Assistant | Great. Here you go! <earcon> | ||
I/O 18 | Welcome to your launchpad for all things Google I/O. This year’s developer festival will be held May 8th through 10th at the Shoreline Amphitheatre. That's in Mountain View, California, next to Google's main campus. Now, you can search for talks, manage your viewing schedule, or ask me anything else you want to know about I/O. | ||
Check failure on line 119 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintLine length
|
||
User | No thanks, that's all I needed | ||
I/O 18 | Come back if there's anything else I/O you’d like to know. | ||
Google Assistant | <earcon> | ||
|
||
## Action links | ||
|
||
Allow users to discover your Action anywhere on the internet by [linking to it | ||
on a web | ||
page](https://developers.google.com/assistant/engagement/assistant-links). You | ||
can direct them to the initial greeting, or you can deep link into a specific | ||
intent (like “Play a game”). | ||
|
||
### Use plain language, and be clear about the link’s destination | ||
|
||
Avoid jargon and other robotic-sounding language. Transparency and simplicity | ||
are key to designing good Action links. | ||
|
||
<figure markdown> | ||
Check failure on line 137 in conversation-design/docs/building-blocks/discovery.md GitHub Actions / markdown-lintInline HTML
|
||
![Plain language](../static/plainlanguage-link.png){ width="300" align="right" } | ||
![Plain language](../static/plainlanguage-2.png){ width="300" align="right" } | ||
<figcaption> | ||
Clear language helps you avoid confusion and build trust with your users. | ||
</figcaption> | ||
</figure> | ||
|
||
### Use appropriately varied greetings | ||
|
||
[Greetings](../conversational-components/greetings.md) should differ based on | ||
the invocation—in this case, the link’s destination. For instance, a link | ||
without intents should lead to an initial greeting (like the example above), | ||
whereas deep links should lead to more specific greetings (depending on the | ||
promised function). | ||
|
||
<figure markdown> | ||
![Plain language](../static/varygreet-link.png){ width="300" align="right" } | ||
![Plain language](../static/varygreet-2.png){ width="300" align="right" } | ||
<figcaption> | ||
A deep link with an intent assigned, like "Purchase tickets", should result in a | ||
short greeting that immediately introduces the function the user has asked for. | ||
</figcaption> | ||
</figure> |