Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/googlecreativelab/aog-canvas-quiz

Canvas Quiz is a starter kit for developers to make custom, voice-enabled question-answer games for the Google Assistant.
https://github.com/googlecreativelab/aog-canvas-quiz

Last synced: 3 months ago
JSON representation

Canvas Quiz is a starter kit for developers to make custom, voice-enabled question-answer games for the Google Assistant.

Awesome Lists containing this project

README 

        

  

    

      This project is no longer actively maintained by the Google Creative Lab but remains here in a read-only Archive mode so that it can continue to assist developers that may find the examples helpful. We aren’t able to address all pull requests or bug reports but outstanding issues will remain in read-only mode for reference purposes. Also, please note that some of the dependencies may not be up to date and there hasn’t been any QA done in a while so your mileage may vary.

      



      For more details on how Archiving affects Github repositories see this documentation .

      



      We welcome users to fork this repository should there be more useful, community-driven efforts that can help continue what this project began.

    

  



# Canvas Quiz



Canvas Quiz is a starter kit for developers to make custom, voice-enabled question-answer games for the Google Assistant. It uses Interactive Canvas, so you can create your own custom graphics and animations. Just deploy the code, put your questions and answers in a Google Sheet, and you’ll have your own quiz up and running.



This is not an official Google product. It’s just an experiment designed to help developers get started building with Interactive Canvas. If you want to learn more about Interactive Canvas, check out the [official docs](https://developers.google.com/actions/interactivecanvas/).



## Setting up



Prerequisites: Node.js and npm. A bit of familiarity with [Actions on Google](https://developers.google.com/actions/conversational/overview) and [Interactive Canvas](https://developers.google.com/actions/interactivecanvas/) is helpful.



1. Make a copy of the [example Google Sheet](https://docs.google.com/spreadsheets/d/1Nk6ZedoaNutKK4aJb1mD_MsKOdyUwFBeay_6cVOplBk/edit).

2. Create a new [Firebase project](https://console.firebase.google.com/).

3. Enable Blaze billing (necessary to use Sheets API and Dialogflow API).

4. Create a new [Dialogflow project](https://console.dialogflow.com). When it asks you for your Google Cloud Project, choose the Firebase project you just created.

5. Install the [Firebase command line tools](https://firebase.google.com/docs/cli).

6. Run `npm run setup` from the root of this repo. You'll need the [gcloud command line tools](https://cloud.google.com/sdk/) installed. (MacOS/Linux only)



**If you ran the setup command successfully, you can skip all the steps below!**



7. Run `npm run installall` to install npm packages for the frontend and backend.

8. In Google Cloud Console, [create a service account](https://console.cloud.google.com/iam-admin/serviceaccounts). Name it whatever you want.

9. For the service account’s role, choose Project > Owner.

10. Click “CREATE KEY”. Choose JSON. Click CREATE. This will download a json file.

11. Move the file into `deploy/functions/modules/auth`.

12. Share the spreadsheet with the email address you just created (needs view access)

13. In the [Google Cloud APIs library](https://console.cloud.google.com/apis/library), find the “Google Sheets API” and enable it.

14. Also find the "Dialogflow API" and make sure its enabled.

15. In the (Dialogflow Console) [https://console.dialogflow.com] for your agent, click the gear icon in the upper left by your agent’s name.  The click “Export and Import”.

16. Click “RESTORE FROM ZIP”. Choose the file `canvas-quiz-starter-agent.zip` from the root of this repo. This will overwrite anything in this agent, and cannot be undone.

17. Open `deploy/functions/modules/config.js` in an editor. Update these variables:

    - `SERVICE_KEY` should be the filename of the JSON key you downloaded.

    - `CANVAS_URL` should be your firebase hosting url + “/canvas”

    - `AUDIO_URL` should be where you want to store any sound effects (can use firebase hosting for this)

    - `IMAGE_URL` should be where you want to store any images (can use firebase hosting for this)

    - `SHEET_ID` should be the id of your Google Sheet. It's in the url: https://docs.google.com/spreadsheets/d/[ID_IS_HERE]/edit

18. Open `deploy/.firebaserc`. Update $PROJECTID to your GCP project.



## Building the frontend

`npm run build` will build the frontend into the `deploy/public/canvas` directory.

`npm run watch` will watch for any changes and build automatically.



## Deploying the frontend and backend

`npm run deploy` will deploy the frontend and backend to Firebase. It will also run a predeploy script that will parse the Google Sheet, update staticquiz.json, and update answer entities on Dialogflow.



Make sure to change your Dialogflow agent’s fulfillment URL to the URL of your cloud function.



## Testing



**Frontend**

The front end can be tested by running `npm run frontend`. The `client/debug-helpers.js` file exposes functions that simulate states sent from the backend, so you can see how the frontend looks and responds to backend changes by calling these functions from the console of your browser.



**Backend**

The first time you want to run your action, go to your Dialogflow agent, and then click “See how it works in Google Assistant” in the right hand column. This will open the Actions on Google simulator.



In the Actions on Google console, go to Deploy > Additional Information. Set the category as “Games & Fun” and scroll down check the box labeled “Interactive Canvas”.



## Styling the frontend

You can customize fonts, colors, spacing, and more in `client/config.js`.

Make sure to [build the frontend](#building-the-frontend) afterwards.



## Working with the frontend

Frontend source files are in the `client` directory. They use [LitElement](https://lit-element.polymer-project.org/) to build HTML components.



Game.js is the primary controller that takes the state from the backend, sends data to components, and handles transitions.



Animations are handled using [Greensock](https://greensock.com/).



## Working with the backend

Backend source files are in the `deploy/functions` directory. Index.js handles the main logic of the quiz. 



Primary modules:

- **config.js**: Holds important info like your project ID, url of the frontend, quiz settings, and spreadsheet settings.

- **DataManager.js**: Handles reading the spreadsheet, putting answers into Dialogflow API, and making data available to the quiz at runtime.

- **History.js**:  Tracks what questions a user has seen and how many times they’ve gotten each question right and wrong. Persists across conversations. Used to prioritize questions the user hasn’t seen and questions the user has gotten wrong frequently.

- **Replier.js**: Handles sending replies to the frontend. Detects device capabilities and adjusts for audio-only, screens without Interactive Canvas support, and screens with Interactive Canvas support. Generally better to use this than `conv.ask()`.

    - You can chain spoken replies like this:

        ```

        conv.replier.addReply(“I want to say this!”);

        conv.replier.addReply(“And this!”);

        conv.replier.send(“One last thing”);

        ```

    - You can send state updates to the frontend like this: 

        `conv.replier.addCanvasUpdate({foo: “bar”});`

    - You can access arbitrary rows in the spreadsheet like this: 

        `conv.replier.getMisc(‘value from id column’)`

    - If a spreadsheet row selected with the `conv.replier.getMisc` function contains a value in the audio column, replier will look for the corresponding audio file in `deploy/firebase/public/audio`.



## Publishing

In the Actions on Google console, go to Deploy > Additional Information. Set the category as “Games & Fun” and scroll down check the box labeled “Interactive Canvas”.



## Less-obvious voice commands

These aren’t directly exposed to the user but could be useful for navigation or testing. If you don’t want them, delete the intents from the Dialogflow agent and delete the corresponding intent-handlers in `deploy/functions/index.js`.



- **“Delete history”** - This will clear everything in user storage, like what questions you’ve seen, your location, etc. If you start another conversation, it’ll be like your first time using the app.

- **“Go to question ___”** - Jumps to a question number. Might mess up your progress, but useful for debugging content without having to reorder the spreadsheet. The number will be the row of the spreadsheet minus 2. So to go to the question on row 44 of the spreadsheet, say “go to question 42”

- **“Debug order linear”** - If said on the homescreen, will force user to go through questions in linear order (useful for testing)

- **“Restart / start over”** - Restarts the quiz

- **“What is this”** - triggers an about page for the quiz

- **“Next question / last question”** - Skips back and forth. Skipped questions are marked as wrong.