Actions SDK and Builder quick start guide

This guide walks you through setting up your environment to build Actions using both the Actions SDK and Actions Builder. You'll carry out the following tasks:

  • Install Node.js: You need this runtime environment to use our Node.js fulfillment library.
  • Install the Firebase CLI: This command-line tool lets you develop and deploy Firebase dependencies, such as web apps for Interactive Canvas, to Firebase Hosting.
  • Install the gactions command-line tool: When developing with the Actions SDK, you use this tool to create, manage, and deploy the Action package for your Action.
  • Create an Actions project: An Actions project is the logical container for your Conversational Actions. You have to create one in the Actions console before you can start building.
  • Initialize and deploy a sample: This simple sample shows you how to get started building Actions powered by Interactive Canvas.

Once you complete this quick start, you can sync your Actions project between your local development environment and the web experience of Actions Builder.

Install Node.js and the Firebase CLI

Download and install Node.js according to the Node.js documentation to use our fulfillment library. Your installation of Node.js also allows you to install the Firebase CLI with npm, and later, to run your conversational fulfillment implementation locally.

Install and set up the Firebase CLI according to the Firebase documentation. The Firebase CLI lets you deploy an Interactive Canvas web app to Firebase Hosting and, if necessary, manually deploy fulfillment to Cloud Functions for Firebase.

Install the gactions command-line tool

Install the gactions command line interface (CLI) tool by downloading an installation package, unpacking it, and configuring your execution path.

To install and configure gactions, follow these steps:

  1. Download the appropriate package for your operating system:

    Platform Package Checksum
    Windows Download SHA256
    Linux Download SHA256
    Mac OS Download SHA256
  2. Extract the package to a location of your choice and add the binary to your environment's PATH variable. Alternatively, extract the package to a location that's already in your PATH variable (for example, /usr/local/bin).

  3. On Linux and Mac, enable execute permissions if necessary:

    chmod +x PATH_TO/gactions
  4. Run the following command to authenticate the CLI. This command starts an authentication flow and requires a web browser:

    gactions login

    When the flow is complete, the CLI automatically authenticates.

Create and set up a project

Before you can use the gactions command-line tool, you must create a project in the Actions console and give gactions access to the project. To create and set up a project, do the following:

  1. Go to the Actions console.
  2. Click New project, enter a project name, and click Create project.
  3. Select a category and click Next.
  4. Select Blank project and click Start building.
  5. Enable the Actions API in the Google Cloud console by following the instructions in Enable and disable APIs. This allows gactions to interact with your project.

Get the hello world sample

The hello world interactive sample shows you how to build a simple Actions project with a single Action powered by Interactive Canvas.

  1. Create an empty directory and initialize the Interactive Canvas sample in that directory. For example, the following code initializes the sample in an interactive-canvas-sample/ directory, which is used as an example throughout this document:

    gactions init interactive-canvas --dest interactive-canvas-sample
    cd interactive-canvas-sample
    
  2. Open the interactive-canvas-sample/sdk/settings/settings.yaml file and change the value of the projectId field to your project's ID.

Deploy and test the sample

After you set up the sample, you can deploy the Interactive Canvas web app and your Actions project. This process creates a draft version of your Actions project that you can deploy to the Actions simulator for previewing and testing:

  1. From the interactive-canvas-sample/ directory, run the following command to deploy the Interactive Canvas web app (the contents of the public/ directory).

    firebase deploy --project PROJECT_ID --only hosting
    

    You can see a rendered version of the web app at the URL returned by the Firebase CLI in a browser: https://PROJECT_ID.web.app.

  2. Open the interactive-canvas-sample/sdk/webhooks/ActionsOnGoogleFulfillment/index.js file and change the value of the CANVAS_URL variable to your project's web app URL.

    const CANVAS_URL = 'https://PROJECT_ID.web.app';
    
  3. From the interactive-canvas-sample/sdk/ directory, run the following command to push the local version of your Actions project to the console as a draft version:

    gactions push
    
  4. From the interactive-canvas-sample/sdk/ directory, run the following command to test your Actions project in the simulator:

    gactions deploy preview
    
  5. Open the link that the command-line tool returns to go to the simulator.

  6. In the simulator, enter "Talk to Interactive canvas sample" to start the Action. You should see a spinning triangle powered by the web app deployed at https://PROJECT_ID.web.app

    Figure 1. The simulator previewing the Actions project