Getting Started to Build your Actions with Yeoman Action Generator

I introduce you the Yeoman Action Generator in this article.

Currently, the ecosystem of Google Assistant is steadily growing up. Of course, there is a development environment to build actions, so developers can build their own actions to extend functionalities of the Google Assistant. The platform is called “Actions on Google”.

When you build actions, actually you need to write a code to interact with users and your action. The code is called as “Fulfillment”. Actions on Google sends user requests to your fulfillment code on HTTP and expects the HTTP response with phrases which respond for the user. It is necessary to handle JSON requests/responses by the fulfillment code, but the format is complex a bit. The Actions on Google Client Library has an ability to handle them, thus developers can write the fulfillment code easily with the SDK.

At the time I wrote this article, there are two official SDKs:

• Actions on Google Client Library for NodeJS
• Actions on Google Client Library for Java

To use them, you need to prepare a development environment. For example, install NodeJS or Java Development Kit, write a build script and an initial code of which you wrote over and over again, configure your project to deploy each Cloud service and so on. But, these code set is almost same for all projects.

You should be able to get the code set by simple way, when you start to build your actions.

Today, you can generate the code set automatically with Yeoman Action Generator. Your code set is generated by the generator after you answer some questions. Basically, the generated code set is work without any touch. That is, you can deploy it to your selected Cloud service quickly.

Supported Action Type, Cloud Service and Language

In the current version, the generator supports the following:

• Action Type: Actions SDK and Dialogflow.
• Cloud Service: Firebase Functions, Google Cloud Functions and Google AppEngine.
• Language: JavaScript, TypeScript and Java.

? Which type do you want to use for your action? (Use arrow keys)
> Actions SDK 
  Dialogflow
? Which cloud service do you want to deploy for your action? (Use arrow keys)
> Firebase Functions 
  Google Cloud Functions 
  Google AppEngine
? Which language do you want to use for your action? (Use arrow keys)
> JavaScript 
  TypeScript
  Java

You can choose each option to generate your action. But, actually there are some limitations like the following:

• Firebase Functions, Google Cloud Functions: JavaScript or TypeScript.
• Google AppEngine: Java only.

According to your selection of the Action Type, a generated source code is changed. Also, if the Actions SDK is selected, an action.json file is created for registering your action package.

How to Install

You can install the Yeoman Action Generator with the following command:

$ npm install -g yo generator-action

Note that you need to install NodeJS 8 or higher before installing them.

Actions SDK, Google Cloud Functions and TypeScript

Here, I introduce a use case so that you can get how to use this generator.

As first case, we try to generate your action written by TypeScript with Actions SDK to deploy to Google Cloud Functions. We assume that the name of the action is “Hello world”.

Prerequisite

You need to install the following before creating your actions:

• NodeJS 8 or higher.
• Google Cloud SDK

Also, you need to update and install the beta version with the following commands:

$ gcloud components update && gcloud components install beta

Create AoG Project

To create an action for Google Assistant, it is necessary to create a new project on Actions on Google (AoG). Visit the Action on Google console, and click the Add/import project button.

Actions on Google console should ask you the name, language and country. You fill in each field, then click the CREATE PROJECT button.

On the next page, click the Actions SDK button. Also, click the OK button on the next popup window.

You need to get the project ID you created just now. Click the gear icon, then click the Project settings menu item.

You should see the Project ID value on the project settings page. Keep it.

Download gactions command

To register your action to Actions on Google, a gactions command is necessary. You can download it from the following page:

gactions CLI | Actions on Google | Google Developers

Download it, and put the command file at some directory where included into your PATH environment.

Generate files with Yeoman Action Generator

Now, let’s generate your project files! In your terminal, execute the command below:

$ mkdir hello-world
$ cd hello-world
$ yo action

You see a welcome message from the generator, and at the same time, the generator asks a first question.

Select the Actions SDK. Then, the generator asks you a cloud service you want to use.

Select the Google Cloud Functions. Next, the generator asks you a language you want to use to write your fulfillment code.

As the last question, the generator asks you the project ID.

Type the project ID which you keep the previous step.

If you already have yarn, the generator generates files, and execute the command yarn install to install dependencies.

After generating files and installing dependencies, you should see like the following end message:

Wow! You got a new code set!

Deploy your Fulfillment Code

The code set you got now works without any touch. That is, you can deploy the code. Execute the following commands:

$ gcloud config set project <YOUR_PROJECT_ID>
$ yarn deploy

If you’re using npm, you can use npm run deploy instead of using yarn. Actually, the yarn deploy command runs two tasks: to build a code written by TypeScript and to deploy it to Google Cloud Platform with gcloud command. If the deploying succeeded, you will see like the following output:

Created .gcloudignore file. See `gcloud topic gcloudignore` for details.
Deploying function (may take a while - up to 2 minutes)...done.                               
availableMemoryMb: 256
entryPoint: fulfillment
httpsTrigger:
  url: https://us-central1-hello-world-*****.cloudfunctions.net/fulfillment
labels:
  deployment-tool: cli-gcloud
name: projects/hello-world-*****/locations/us-central1/functions/fulfillment
runtime: nodejs8
serviceAccountEmail: hello-world-*****@appspot.gserviceaccount.com
sourceUploadUrl: https://storage.googleapis.com/gcf-upload-us-central1-12643551-0839-****-****-3518bb26eda4/77dea571-****-****-b69a-924ffecff74f.zip?GoogleAccessId=service-414****89196@gcf-admin-robot.iam.gserviceaccount.com&Expires=1552270433&Signature=EoZWuBug06v8036umcw1O4BpJYOETvYA%2BZrg9aMhe7H5EkD8Hi%2FYnH%2FO0B%2B3mGEKR1tlNSAfsSVU8MN9lcE9FvO3U0JZLfFTj4sUyaz6A%2BTY0E%2F6lPfGv%2FsCzvOB74fU5zxWDbgH4f9jq1PWZNqjd0lIyZciNXD9E%2BWi4...
status: ACTIVE
timeout: 60s
updateTime: '2019-03-11T01:50:29Z'
versionId: '1'

In the output above, the httpsTrigger:url is important.

Register your Action Package

You already have an action package file named action.json. However, you need to edit the file. Open the action.json file with your favorite text editor.

{
  "actions": [
    {
      "name": "MAIN",
      "fulfillment": {
        "conversationName": "myFulfillment"
      },
      "intent": {
        "name": "actions.intent.MAIN"
      }
    }
  ],
  "conversations": {
    "myFulfillment": {
      "name": "myFulfillment",
      "url": "<YOUR_FULFILLMENT_URL>",
      "fulfillmentApiVersion": 2
    }
  },
  "locale": "en"
}

There is <YOUR_FULFILLMENT_URL> in the “conversation.myFulfillment.url”. Replace the placeholder with the URL of your fulfillment code you deployed just now. Then, execute the following command:

$ yarn update-action

If successfully, you will see like the following output:

Your app for the Assistant for project hello-world-***** was successfully updated with your actions. Visit the Actions on Google console to finish registering your app and submit it for review at https://console.actions.google.com/project/hello-world-*****/overview

Test your Action

Open the Actions on Google console, and select your action project. Then, click the Simulator menu item on the left navigation menu.

The Action Simulator is opened. You can invoke your action with the phrase “Talk to my test app”.

Great! We could confirm that the action worked.

What files did the generator generate?

After generating, you have the following files:

hello-world
├── action.json      - Action Package file.
├── node_modules     - Generated by `yarn install`.
├── package.json     - Node project file.
├── src
│   └── index.ts     - The fulfillment code.
├── tsconfig.json    - For TypeScript.
├── tslint.json      - For TypeScript.
└── yarn.lock        - Generated by `yarn install`.

The current version 0.2.7, the following code is created for the fulfillment code by the generator:

import * as functions from 'firebase-functions';
import { actionssdk } from 'actions-on-google';
const app = actionssdk({
  debug: true
});
app.intent('actions.intent.MAIN', (conv): void => {
  conv.close('Hello, world!');
});
exports.fulfillment = functions.https.onRequest(app);

That is, it is a simple “Hello, world” program. I think that this is a good start point at building your action.

Conclusion

The Yeoman Action Generator project has been hosted on the GitHub.

yoichiro/generator-action

I intend to add other supports for Azure and etc. Also, I think that it is necessary to generate code which has other features: Sign-in, Transactions, i18n and so on, not only a simple “Hello, world” output.

I expect that you can build your actions more easily with the generator. Feel free to let me know your idea to improve the generator!