How to use Google Sign-In for the Assistant
There are so many use cases of the Google Assistant. In the use cases, there will be many actions which can provide high personalized-services, if they can authenticate users. We already have many experiences that many services on the internet require a login (that is a user authentication). In the Google Assistant, the user authentication is very important as well. Also, it will bring high possibility of the conversion rate, if the steps of the user authentication are simple. Furthermore, if users can log in via voice-activated devices, it will be more better.
Google Sign-In for the Assistant is a feature to authenticate users easily with Google Accounts in actions. Both users of actions and developers of actions can use the feature very easily. I’m writing this story on Sep 6, 2018. Perhaps, this feature was provided as Developer Preview until the last week, and it worked on the en-US locale only, I remembered. But, the official document has already beed updated, and the “Developer Preview” words has already been removed. That is, I think that we can say that the Google Sign-In for the Assistant feature graduated from the Developer Preview and published as a stable feature. Of course, the feature works on other locales including ja-JP!
I would like to introduce how to integrate the Google Sign-In for the Assistant into your action.
Configuration on the Actions on Google Console
First, before writing a code, you need to configure some settings to use the Google Sign-In for the Assistant on the Actions on Google Console. Note that an error will occur at using the Google Sign-In for the Assistant from your code, if we forget the configuration.
There is an “Account Linking” menu item on the left menu in the Actions on Google Console. In your action, click the “Account Linking” menu item.
After changing the page, select the “Yes, allow users to sign up for new accounts via voice” item on the right side, then click the “NEXT” button.
Next, select the “Google Sign In” as the Linking type, and click the “NEXT” button.
Here, a Client ID is issued and displayed. Although it is a gray-out, you can select the Client ID string. You need to write down the Client ID as a memo. Because you will write the Client ID string into your code later. After writing the memo, click the “SAVE” button on the bottom of the right.
The configuration was completed on the Actions on Google Console side.
Calling the Google Sign-In for the Assistant from your code
Now, you can use the Google Sign-In for the Assistant from your code. It is very easy to use the Google Sign-In for the Assistant, if you use the actions-on-google-nodejs SDK.
Setting the Client ID
You should already have the Client ID issued by the previous step on the Actions on Google Console. It is necessary to pass the Client ID to the SDK.
If you use a Dialogflow, write a code as like the following.
const {
dialogflow
} = require("actions-on-google");
const app = dialogflow({
clientId: <YOUR_CLIENT_ID>
});If you use an Actions SDK, write a code as like the following.
const {
actionssdk
} = require("actions-on-google");
const app = actionssdk({
clientId: <YOUR_CLIENT_ID>
});Sending a sign-in request
You can send a request of the user authentication with the Google Sign-In for the Assistant to the Actions on Google using a “SignIn” class provided by the SDK. You can send the request at anytime when you want to authenticate the user.
If you use the Dialogflow, write a code as like the following.
const {
dialogflow,
SignIn
} = require("actions-on-google");
...
app.intent("Start Sign-in", conv => {
conv.ask(new SignIn("To personalize"));
});If you use the Actions SDK, write a code as like the following. This code is almost same as the code above for the Dialogflow.
const {
actionssdk,
SignIn
} = require("actions-on-google");
...
app.intent("actions.intent.TEXT", conv => {
conv.ask(new SignIn("To personalize"));
});By the code above, the Google Assistant ask the user the request of the user authentication. See the screenshot below. You see the dialog at user authentication. In this case, the action name is “The Arekore Testing” (the Japanese word “Arekore” means “various” in English). There is an intent to start the Google Sign-In for the Assistant flow, and the intent has a training phrase “want to sign in”.
It seems that the template of the message is like the following.
<CONTEXT_STRING>, you’ll need an account with <ACTION_NAME>. To create a new one for you, I’ll just need some info. If you want more details, say "Tell me more. " So, can I ask Google for your name, email address, and profile picture?The “<CONTEXT_STRING>” is a string passed to the constructor of the “SignIn” class. When the user says “Tell me more”, the Google Assistant will say like the following.
The user needs to answer either “Yes” or “No”.
Retrieving the result of the Sign-In
When answering by the user, the Actions on Google sends an “actions_intent_SIGN_IN” event to your action to tell the result of the user authentication. You need to handle the result by preparing a fulfillment code.
If you use the Dialogflow, you need to create an intent to handle the “actions_intent_SIGN_IN” event. Here, the intent name is “Get Signin”. Write a fulfillment code as like the following.
app.intent("Get signin", (conv, params, signin) => {
if (signin.status === "OK") {
conv.ask("Sign-in done.");
} else {
conv.ask("You need to sign in to personalize.");
}
});If you use the Actions SDK, write a code as like the following. It also is as almost same as the code for the Dialogflow.
app.intent("actions_intent_SIGN_IN", (conv, params, signin) => {
if (signin.status === "OK") {
conv.ask("Sign-in done.");
} else {
conv.ask("You need to sign in to personalize.");
}
});The result of the user authentication is passed to the 3rd argument of the callback function which is passed to the “app.intent()” function. The 3rd argument is defined in the “SignInValue”. Either value defined by the “SignInStatus” will be passed as the “status” value. Basically, if the value is “OK”, the user accepts the user authentication. Otherwise, the user denies the user authentication.
When the user says “No”, the code above sends the “You need to sign in to personalize.” message as the reply. The Google Assistant doesn’t say the message only. Actually, the following message replied.
When the user says “Yes”, the Google Assistant asks the user the following message again. That is, the user authentication is not completed at this time.
Here, the user can say “No” to deny the authentication. When saying “No”, the “signin.status” value is not “OK”.
When the user says “Yes” against the Google Assistant, the signing in is confirmed, the “signin.status” value is “OK”. In the code above, the fulfillment code returns the “Sign-in done” message as the reply from the action. But, as same as the previous case, the Google Assistant adds other messages to the message string returned by the action.
At almost same time, the user will receive like the following email. Sorry, the screenshot below is for Japanese users.
This email content has a URL to revoke the authentication.
Retrieving the user profile information
After authenticating the user with the Google Sign-In for the Assistant, the action can retrieve the user’s profile information. For instance, after the authentication, the Actions on Google sends an ID Token represented by JWT to the action at each time when the user says something to the action.The actions-on-google-nodejs SDK handles the token, validate it, parses it and provides the user’s information to the fulfillment code.
You can retrieve the user profile information with “conv.user.profile.payload”. If the value is undefined, your action can recognize that the user is not authenticated yet. The following code is a sample to show the user’s information with a BasicCard rich response.
const {
...
BasicCard,
Image
} = require("actions-on-google");
app.intent("Show User Profile", conv => {
const payload = conv.user.profile.payload;
if (payload) {
const userId = payload.aud;
const name = payload.name;
const givenName = payload.given_name;
const familyName = payload.family_name;
const email = payload.email;
const emailVerified = payload.email_verified;
const picture = payload.picture;
conv.ask("This is your profile information.");
conv.ask(new BasicCard({
text: `ID:${userId}
Name:${name}
Given name:${givenName}
Family name:${familyName}
Email:${email}
Email verified:${emailVerified}`,
image: new Image({
url: picture,
alt: "Profile Image"
})
}));
} else {
conv.ask("Not signed in yet.");
conv.ask(new Suggestion("want to sign in"));
}
});The screenshot below is a sample response after sending the BasicCard response on the Actions Simulator.
When I tested this feature at writing this story, the following user information can be retrieved.
- User ID: “conv.user.profile.payload.aud”
- Name: “conv.user.profile.payload.name”
- Family name: “conv.profile.payload.family_name”
- Given name: “conv.profile.payload.given_name”
- Profile image URL: “conv.profile.payload.picture”
- Email address: “conv.profile.payload.email”
- Whether Email address verified: “conv.profile.payload.email_verified”
Impossible things with the Google Sign-In for the Assistant
The Google Sign-In for the Assistant feature is for an authentication with Google Accounts, is not for an authorization. Therefore, the following things are not possible.
- The Actions on Google passes the ID Token. The Actions on Google does NOT pass an access token.
- Currently, you cannot require additional information of the user profile. You can retrieve the information listed above only.
Conclusion
We cannot use the Google Sign-In in the Account Linking with the OAuth. In the term of the Actions on Google, we need to use the Google Sign-In for the Assistant feature, if we want to authenticate users with Google Accounts. However, the Google Sign-In for the Assistant was as Developer Preview and was for en-US locale only until now. So many developers were waiting the release of this feature, I guess.
Today, you can use the Google Sign-In for the Assistant feature in your action. Please integrate this feature into your action soon, and bring more rich experiences to many users from your action!
