Build projects

Actions Builder Actions SDK

An Actions project packages all of your Actions into a single container. You publish this project to Actions on Google so Google Assistant knows how to discover and invoke your conversational experiences.

Figure 1. Actions project structure

You use the following low-level components to build your Actions project:

• Settings and resources define project metadata and resources like project icons. Google uses this information to publish your Actions to the Assistant directory, so that users can discover and invoke them.

• Intents represent a task to be carried out, such as some user input or a system event that needs processing. The most common type of intent you'll use are user intents. These intents let you declare training phrases that are naturally expanded by the NLU (natural language understanding) engine to include many more, similar phrases. The NLU uses the aggregation of these phrases to train a language model that the Assistant uses to match user input. During a conversation, if some user input matches the intent's language model, the Assistant runtime sends the intent to your Action, so that it can process it and respond to the user.

• Types let you extract structured data from user input. By annotating training phrases with types, the NLU can extract relevant, structured data for you, so you don't have to parse open-ended input.

• Scenes process intents and are the main logic executors for your Actions. They can do slot-filling, evaluate conditional logic, return prompts to the user, and even call on external web services to carry out business logic. In combination with intents, scenes give you a powerful way to detect specific user input or system events and to carry out corresponding logic.

• Prompts define static or dynamic responses that you use to respond back to users.

• Webhooks let you delegate extra work to web services (fulfillment), such as validating data or generating prompts. Your Actions communicate with your fulfillment through a JSON-based, webhook protocol.

• Interactive Canvas lets you create rich and immersive experiences with web apps that utilize HTML, CSS, and JavaScript.

Create a project

You must create a project in the Actions console before you can develop for Google Assistant. To create a project:

1. Go to the Actions console.
2. Click New project.
3. Enter a name for your project and click Create Project.
4. In the What kind of Action do you want to build? screen, select a category that best represents your project and click Next.
5. In the How do you want to build it screen, select a way to build and click Start building. For example, you can start with an empty project or with a sample.

Key Point: If you are building for Interactive Canvas, follow these additional steps:

1. If you did not select the Game card on the What type of Action do you want to build? screen, click Deploy in the top navigation. Under Additional Information, select the Games & fun category. Click Save.
2. Click Develop in the top navigation of the Actions console.
3. Click Interactive Canvas in the left navigation.
4. Under Does your Action use Interactive Canvas?, select Yes.
5. Optional: Enter your web app URL into the Set your default web app URL field. This action adds a default Canvas response with the URL field to your Main invocation.
6. Click Save.

Create a local Actions SDK project

Once you have created an Actions project in the Actions console, you can initialize a project in your local development environment.

To initialize an Actions SDK project from an existing Actions project, follow these steps:

1. Create an empty directory for the Actions project on your local filesystem.
2. In this empty directory, create an sdk directory.
3. Change your working directory to the sdk directory in your terminal.

Start with an empty project

If you want to start from the empty project you've just created in the console, run gactions pull --project-id <my-project-id>.

$ mkdir myAction
$ cd myAction
$ mkdir sdk
$ cd sdk
$ gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk

Start with a sample project

If you want to start from a sample project, run gactions init <sample name>.

$ mkdir actions-test
$ cd actions-test
$ mkdir sdk
$ cd sdk
$ gactions init question
Writing sample files for question.
✔ Done. Please checkout the following documentation - https://developers.google.com/assistant/conversational/build on the next steps on how to get started.

Define project information

Note: See the Directory information documentation for more details on how to manage project information.

Your project's settings and resources define information about your project like feature and surface support, supported locales, display name, description, logos, and more. The following table describes the main settings and resources you provide. Actions on Google uses this information to deploy and publish your project to the Assistant directory.

Name	Description
Directory information	Provides information so that Actions on Google can publish your project to the Assistant directory. Includes metadata and desecriptions about your project and image resources for logos and banner images.
Location targeting	Configures the locales that your Actions are available in.
Surface capabilities	Configures the surfaces that your Actions are available on.
Company details	Specifies contact information for your company.
Brand verification	Connect a website or Android app that you own to gain extra benefits such as reserved invocation names and website linking within your Actions.
Release	Configures different testing and production releases for your Action for testing and production.
Assistant links	Let users invoke your Actions from your web properties.

To define project information:

1. Define global settings for your Actions project in sdk/settings/settings.yaml. See the Settings reference documentation for supported values.

   The following snippet shows an example sdk/settings/settings.yaml file:

   accountLinking:
     enableAccountCreation: true
     linkingType: GOOGLE_SIGN_IN
   category: GAMES_AND_TRIVIA
   projectId: my-project-id
   ...
   

   Key Point: If you are building for Interactive Canvas, follow these additional steps:

   1. Set the category field in your settings.yaml file to GAMES_AND_TRIVIA to best describe and help users discover your Action.
   2. Set the usesInteractiveCanvas field in your settings.yaml file to true.

2. Define settings that can vary based on the user's locale (for example, invocation phrases in different languages) in an sdk/settings/<locale>/settings.yaml file, replacing locale with your target locale.

   See the LocalizedSettings reference documentation for supported values.

   The following snippet is an example for English settings defined in an sdk/settings/en/settings.yaml file:

   localizedSettings:
     developerEmail: [e-mail]
     developerName: Developer Name
     displayName: My Display Name
     fullDescription: full description of the action
     largeBannerImage: https://path/to/large/banner
     privacyPolicyUrl: http://path/to/privacy/policy
     sampleInvocations:
     - Talk to My Display Name
     shortDescription: short description of the action
     smallLogoImage: https://path/to/small/logo
     voice: female_1
   ...
   

Add resources

You can store resources such as image files, audio files, and strings in your Actions project and reference them from configuration files (for example, prompt definitions or conditions) using the system defined $resources variable.

Project resources are stored under resources/, and each resource type is assigned a folder in the directory.

You can localize resources by creating locale specific folders in the resource type folder, for example you can store Spanish versions of your strings in resources/strings/es/<filename>.yaml.

Images

Image files are stored in resources/images/, and you can reference them with $resources.images.<name of the image file without file extension>. The allowed file extensions are:

• gif
• png
• jpg
• jpeg

For example, if the English version of the small logo is saved in resources/images/en/square.png and the English version of the large banner is saved in resources/images/en/landscape.jpg respectively, sdk/settings/en/settings.yaml from the previous example would become:

localizedSettings:
  developerEmail: [e-mail]
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action

  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action

  smallLogoImage: $resources.images.square
  voice: female_1
...

Audio files

Audio files are stored in resources/audio/, and you can reference them with $resources.audio.<name of the audio file without file extension>.

The allowed file extensions are:

• mp3
• mpeg

For example, you can reference audio recordings from prompts:

candidates:
  - first_simple:
      variants:
        - speech: your speech response
    content:
      media:
        mediaType: audio
        mediaObjects:
          - name: media name
            description: media description
            url: $resources.audio.intro

Strings

Strings are stored in resources/strings/ as .yaml files. Each file contains a map of string keys and associated values, which can be single strings or lists of strings. You can reference the values using $resources.strings.<name of the image file without file extension>.<key> for single string values or to get a random value from a list, and $resources.strings.<name of the image file without file extension>.<key>.<numerical index> for a specific string value within a list.

For example, using resource strings for strings localization, sdk/settings/en/settings.yaml from the previous example could become:

localizedSettings:
  developerEmail: [e-mail]
  developerName: $resources.strings.appinfo.developerName
  displayName: $resources.strings.appinfo.displayName
  fullDescription: $resources.strings.appinfo.fullDescription
  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: $resources.strings.appinfo.privacyPolicyUrl
  sampleInvocations:
  - $resources.strings.invocations.sample
  shortDescription: $resources.strings.appinfo.shortDescription
  smallLogoImage: $resources.images.square
  voice: female_1
...

Test projects in the simulator

Note: See the Actions simulator documentation for complete information about testing your projects.

The Actions console provides a simulator to preview your Actions in. The simulator lets you see debug information, set device capabilities, simulate locale, and more.

Figure 3. The main areas of the simulator: (1) user input, (2) device view, (3) options and settings, and (4) conversation log.

To test a project:

1. Run gactions deploy preview to deploy your Action to "preview" and enable testing in the simulator.
2. Open the URL in the command output to access the Simulator.

$ gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview