google / actions-on-google-flashcards-template-sdk

Migration from the Flash Cards template to the Actions Builder

This step-by-step guide describes the project and its source code for the conversion from the Flash Cards template to the Actions Builder platform.

Directory structure

The following table describes the file structure for this project:

• converter: Sheets and locales conversion tool
• functions: Fulfillment webhook source code
• sdk: Action SDK resource files

Step 1: Prerequisites

Before you begin the migration, perform the following steps:

1. Install Node.js and NPM as follows:

   • Install them with Node Version Manager (nvm) for Linux and Mac or nvm for Windows.
   • The webhook runtime requires Node.js version 10 or higher.

2. Install the Firebase CLI as follows:

   1. Install it with MAJOR version 8. To do so, run the following command: npm install -g firebase-tools@^8.0.0.
   2. Run firebase login with your Google Account.

3. Install the Actions CLI as follows:

   1. Extract the package to your chosen location and add the binary to your environment‘s PATH variable. Alternatively, extract the package to a location already in your PATH variable, such as /usr/local/bin.
   2. Run gactions login with your Google Account.

4. Go to Google Sheet Node.js Quickstart as follows:

   1. From that page, go to Step 1, and click Enable the Google Sheets API.
   2. Enter a project name or select the default name, "Quickstart", and click Next.

      Note: This project isn‘t the same as a new "Actions on Google" project needed for migration.

   3. For Configure your Oauth client, select Desktop app.
   4. Click Create.
   5. To download credentials.json, click Download client configuration.
   6. Save the JSON file in the converter/ directory.

Step 2: Setup

Create a new project in Actions Console and upgrade the Firebase price plan as described here.

Create a new project in Actions Console

Perform the following steps:

1. Go to Actions on Google Console.
2. Select New project > Create project.
3. Select What kind of Action do you want to build? > Game > Blank project.

To find your Project ID, go to Actions on Google Console for your project, and go to More ⋮ > Project settings > Project ID.

Note: Don't confuse the Project ID with the Project Name.

Upgrade the Firebase price plan

From the Firebase Console, select the same newly created project from Actions Console and upgrade its price plan to Blaze (pay as you go).

Caution: A Blaze plan is required for Cloud Functions for Node.js version 10 runtime.

Step 3: Migration

Perform the steps described here.

Sample sheets to create a new action

To create a new Flash Cards action, make a copy of the Flash Cards sample sheet in your preferred locale-specific language. Update the sheet with your data. Alternatively, you can use your current Flash Cards data sheet. Refer to the following links to the Flash Cards sample sheets, in your preferred locale-specific language:

• de
• en
• en-AU
• en-CA
• en-GB
• en-IN
• en-US
• es
• es-419
• es-ES
• fr
• fr-CA
• fr-FR
• hi
• id
• it
• ja
• ko
• pt-BR
• ru
• th

Update the Flash Cards sheet ID

Open converter/config.js and update the LOCALE_TO_SHEET_ID mapping with your own Flash Cards data sheet ID for the specific locale you need to convert, as follows:

1. Determine the Sheet ID, which is hard-coded as part of the sheet URL:
   https://docs.google.com/spreadsheets/d/<SHEET_ID>/edit#gid=0.
2. Uncomment the specific locales you need to convert and update the sheet ID.
3. The sheet IDs provided in converter/config.js are the default sample sheets for each locale. To create a new Flash Cards action, make a copy of the sample sheet and update it with your own data.
4. Verify that the data sheet is owned by the same Google Account that performs the migration.

After you've updated the sheet ID, you have two options for how to proceed with the migration.

Automatic migration script: Option 1

To automatically run all the migration steps, go to the root directory of the project, and run the following command: ./build.sh <PROJECT_ID>. Be aware of the following guidance:

• When the script is run for the first time, it asks you to grant read access to your sheets. To do so, go to the URL it provides, grant read access, and copy the authorization code and enter it when prompted by the script.
  If you're taken to a warning page that says, "This app isn't verified," click Advanced. From the dropdown text that appears, click Go to Quickstart (unsafe) and continue the authorization process.
• If you encounter an issue, you can, instead, perform a manual migration.

Manual migration: Option 2

To manually migrate the project, perform the steps described here:

1. Run the sheet and locale conversion script.
2. Deploy the webhook to Cloud Functions for Firebase.
3. Use Actions CLI to push and preview your project.

Run the sheet and locale conversion script

Perform the following steps:

1. Go to the converter/ directory. To do so, go to the root directory of the project and run cd converter.
2. Run npm install.
3. Run npm run convert -- --project_id <PROJECT_ID>. Be aware of the following guidance:
   • When the script is run for the first time, it asks you to grant read access to your sheets. To do so, go to the URL it provides, grant read access, and copy the authorization code and enter it when prompted by the script.
     If you're taken to a warning page that says, "This app isn't verified," click Advanced. From the dropdown text that appears, click Go to Quickstart (unsafe) and continue the authorization process.
   • After the conversion script completes, the parsed sheet data is added to the functions/data/ directory, and the locale-specific data is added to the sdk/ directory.

Deploy the webhook to Cloud Functions for Firebase

Perform the following steps:

1. Go to the functions/ directory. To do so, go to the root directory of the project and run cd functions.
2. Run npm install.
3. To deploy the "v1" webhook, run firebase deploy --project <PROJECT_ID> --only functions:flashcards_v1.
   • After you release a version of the action, you can update your webhook and test your changes without affecting your production action. To do so, we recommend that you update the FUNCTION_VERSION value in functions/config.js. Then, deploy to a new webhook URL, such as flashcards_v2.

Use Actions CLI to push and preview your project

Perform the following steps:

1. Go to the sdk/ directory. To do so, go to the root directory of the project and run cd sdk.
2. To login to your Google Account, run gactions login.
3. To push your project, run gactions push.
   • To fix the validation warnings, go to Actions Console, and from the Deploy section, update the missing directory information.
   • If you need to sync the changes made in the Actions Builder Console with your local sdk/ directory, run gactions pull.
4. To deploy the project to the preview environment, run gactions deploy preview.

Step 4: Test the converted action

You can test your action on any Google Assistant-enabled device that's signed into the same account used to create the project. You can also use the Actions on Google Console's simulator to test most features and preview on-device behavior.

Support and additional resources

If you encounter an issue or need additional information, refer to any of the following:

• If you have a question, the following forums are significantly helpful:
  • StackOverflow
  • Reddit's Assistant Developer Community
• If you find any bugs, report them through GitHub.
• To learn more about Actions on Google, refer to Google Assistant's developer documentation.
• For guided, hands-on practice with Actions on Google, try some of the Codelabs for Google Assistant.

Contribute

To contribute to this project, adhere to the steps described on the Contributing page.

License

For more information on our license, read the License.