googlehome-plugin.md

Table of Contents generated with DocToc

• Nightscout Google Home/DialogFlow Plugin
  • Overview
  • Activate the Nightscout Google Home Plugin
  • Create Your DialogFlow Agent
    • Do you use Authentication Roles?
    • What questions can you ask it?
    • Using the Alpha Tester feature
  • Updating your agent with new features
  • Adding support for additional languages
  • Adding Google Home support to a plugin

Nightscout Google Home/DialogFlow Plugin

Overview

To add Google Home support for your Nightscout site, here's what you need to do:

1. Activate the googlehome plugin on your Nightscout site, so your site will respond correctly to Google's requests.
2. Create a custom DialogFlow agent that points at your site and defines certain questions you want to be able to ask.

Activate the Nightscout Google Home Plugin

1. Your Nightscout site needs to be new enough that it supports the googlehome plugin. It needs to be version 13.0.0 (Ketchup) or later. See updating my version if you need a newer version.
2. Add googlehome to the list of plugins in your ENABLE setting. (Environment variables are set in the configuration section for your monitor. Typically Azure, Heroku, etc.)

Create Your DialogFlow Agent

BEFORE YOU GET STARTED: Please read the section below on the highly-recommended use of the Alpha tester feature.

1. Download the agent template in your language for Google Home here.
   • If you're language doesn't have a template, please consider starting with the en-us template, then modifying it to work with your language, and making a pull request or submitting an issue with your translated template to share it with others.
2. Sign in to Google's Action Console
   • Make sure to use the same account that is connected to your Google Home device, Android smartphone, Android tablet, etc.
3. Click on the "New Project" button.
4. If prompted, agree to the Terms of Service.
5. Give your project a name (e.g. "Nightscout") and then click "Create project".
6. When asked what kind of Action you want to build, select "Custom" and then click the "Next" button.
7. When selecting how you want to build the project, scroll down to the bottom of the screen and click the link to build it using DialogFlow.
8. Click on the "Develop" tab at the top of the sreen.
9. Click on "Invocation" in the left navigation pane.
10. Set the display name (e.g. "Night Scout") of your Action and set your Google Assistant voice.
    • Unfortunately, the Action name needs to be two words, and is required to be unique across all of Google, even though you won't be publishing this for everyone on Google to use. So you'll have to be creative with the name since "Night Scout" is already taken.
11. Click "Save" in the upper right corner.
12. Navigate to "Actions" in the left nagivation pane, then click on the "Add your first action" button.
13. Make sure you're on "Cutom intent" and then click "Build" to open DialogFlow in a new tab.
14. Sign in with the same Google account you used to sign in to the Actions Console.
    • You'll have to go through the account setup steps if this is your first time using DialogFlow.
15. Verify the name for your agent (e.g. "Nightscout") and click "CREATE".
16. In the navigation pane on the left, click the gear icon next to your agent name.
17. Click on the "Export and Import" tab in the main area of the page.
18. Click the "IMPORT FROM ZIP" button.
19. Select the template file downloaded in step 1.
20. Type "IMPORT" where requested and then click the "IMPORT" button.
21. After the import finishes, click the "DONE" button followed by the "SAVE" button.
22. In the navigation pane on the left, click on "Fulfillment".
23. Enable the toggle for "Webhook" and then fill in the URL field with your Nightscout URL: https://YOUR-NIGHTSCOUT-SITE/api/v1/googlehome
    • If you use Authentication Roles, you'll need to add a bit to the end of your URL. See the section below.
24. Scroll down to the bottom of the page and click the "SAVE" button.
25. Click on "Integrations" in the navigation pane.
26. Click on "INTEGRATION SETTINGS" for "Google Assistant".
27. Under "Implicit invocation", add every intent listed.
28. Turn on the toggle for "Auto-preview changes".
29. Click "CLOSE".

That's it! Now try asking Google "Hey Google, ask your Action's name how am I doing?"

Do you use Authentication Roles?

If you use Authentication Roles, you will need to add a token to the end of your Nightscout URL when configuring your Webhook.

1. In your Nightscout Admin Tools, add a new subject and give it the "readable" role.
   • If you really would like to be super specific, you could create a new role and set the permissions to api:*:read.
2. After the new subject is created, copy the "Access Token" value for the new row in your subject table (don't copy the link, just copy the text).
3. At the end of your Nighscout URL, add ?token=YOUR-TOKEN, where YOUR-TOKEN is the Access Token you just copied. Your new URL should look like https://YOUR-NIGHTSCOUT-SITE/api/v1/googlehome?token=YOUR-TOKEN.

What questions can you ask it?

See Interacting with Virtual Assistants for details on what you can do with Google Home.

Using the Alpha Tester feature

If you use your Google Action on the same account as the one you used to create it, you will find that Google disables Test Mode for the action after some period of time, and you have to log in to the Actions console, and open the testing tab to re-enable testing for you to continue to use it. To overcome this limitation, you can use the Alpa Testers feature of Google Actions. To do so, you need to follow a few extra steps:

1. Figure out which Google account you use for your Google Assistant.
2. Use or create a different account to follow the instructions to create your Google Action and DialogFlow agent.
3. Once you verify your Action is working, navigate to the Actions Console, and open your project.
4. Navigate to the "Deploy" tab, then open the "Release" page in the left navigation pane.
5. Expand the "Alpha" section, then click on the "Create a release" button, and then follow the directions to create a release.
   • You may need to fill out some extra information, such as a Privacy Policy (example), descriptions (e.g. both could be "Tools and stuff to help my partner and I do things better"), and testing instructions (e.g. "Since this is built entirely for myself and my partner, don't expect too much out of this one."). Because this will be for personal use, it's recommended that you keep all of these as vague as possible.
6. Click the "Manage Alpha Testers" button.
7. Enter the email address of the account you use for your Google Assistant (found in step 1). Enter the emails of any other people you would like to have access to talk to your Action (e.g. a spouse).
8. Click the "Save" button.
9. Copy the "Opt-in link" and open it on a device logged in with your account from step 1. Repeat for any other emails you added two steps ago. If the link doesn't work right away, try again in a couple hours.
10. Follow any directions to setup the account as an Alpha Tester.

Updating your agent with new features

As more work is done on Nightscout, new ways to interact with Nighscout via Google Home may be made available. To be able to use these new features, you first will need to update your Nightscout site, and then you can follow the steps below to update your DialogFlow agent.

1. Make sure you've updated your Nightscout site first.
2. Download the latest skill template in your language.
   • If your language doesn't include the latest features you're looking for, you're help translating those new features would be greatly appreciated!
3. Sign in to the DialogFlow developer portal.
4. Make sure you're viewing your Nightscout agent (there's a drop-down box immediately below the DialogFlow logo where you can select your agent).
5. Click on the gear icon next to your agent name, then click on the "Export and Import" tab.
6. Click the "RESTORE FROM ZIP" button.
7. Select the template file you downloaded earlier, then type "RESTORE" in the text box as requested, and click the "RESTORE" button.
8. After the import is completed, click the "DONE" button.
9. Make sure to follow any directions specific to the Nightscout update. If there are any, they will be noted in the release notes.
10. If you use the Alpha Testers feature (see Using the Alpha Tester feature above), create a new release.
11. Enjoy the new features!

Adding support for additional languages

If the translations in Nightscout are configured correctly for the desired language code, Nightscout should automatically respond in that language after following the steps below.

If you add support for another language, please consider making a pull request or submitting an issue with your translated template to share it with others. You can export your translated template by going to the settings of your DialogFlow agent (the gear icon next to the project's name in the left nagivation pane), going to the "Export and Import" tab, and clicking "EXPORT AS ZIP".

1. Open your DialogFlow agent.
   • Get to your list of agents at https://console.dialogflow.com/api-client/#/agents and click on the name of your Nightscout agent.
2. Click on the "Languages" tab.
3. Click the "Add Additional Language" drop-down box.
4. Select your desired language.
5. Click the "SAVE" button.
   • Note the new language code below the agent's name. e.g. if you're using the English template and you added Spanish, you would see two buttons: "en" and "es".
6. Click on "Intents" in the left navigation pane.
7. For each intent in the list (NOT including those that start with "Default" in the name):
   1. Click on the intent name.
   2. Note the phrases used in the "Training phrases" section.
      • If the phrase has a colored block (e.g. metric or pwd), click the phrase (but NOT the colored block) and note the "PARAMETER NAME" of the item with the same-colored "ENTITY".
   3. Click on the new language code (beneath the agent name near the top of the navigation pane).
   4. Add equivalent or similar training phrases as those you noted a couple steps ago.
      • If the phrase in the orginal language has a colored block with a word in it, that needs to be included. When adding the phrase to the new language, follow these steps to add the colored block:
        1. When typing that part of the training phrase, don't translate the word in the block; just keep it as-is.
        2. After typing the phrase (DON'T push the Enter key yet!) highlight/select the word.
        3. A box will pop up with a list of parameter types, some of which end with a colon (:) and a parameter name. Click the option that has the same parameter name as the one you determined just a few steps ago.
        4. Press the Enter key to add the phrase.
   5. Click the "SAVE" button.
   6. Go back and forth between your starting language and your new language, adding equivalent phrase(s) to the new language. Continue once you've added all the equivalent phrases you can think of.
   7. Scroll down to the "Action and parameters" section.
   8. If any of the items in that list have the "REQUIRED" option checked:
      1. Click the "Define prompts..." link on the right side of that item.
      2. Add phrases that Google will ask if you happen to say something similar to a training phrase, but don't include this parameter (e.g. if you ask about a metric but don't say what metric you want to know about).
      3. Click "CLOSE".
   9. Scroll down to the "Responses" section.
   10. Set just one phrase here. This will be what Google says if it has technical difficulties getting a response from your Nightscout website.
   11. Click the "SAVE" button at the top of the window.
8. Click on the "Entities" section in the navigation pane.
9. For each entity listed:
   1. Click the entity name.
   2. Switch to the starting language (beneath the agent name near the top of the left navigation pane).
   3. Click the menu icon to the right of the "SAVE" button and click "Switch to raw mode".
   4. Select all the text in the text box and copy it.
   5. Switch back to your new language.
   6. Click the menu icon to the right of the "SAVE" button and click "Switch to raw mode".
   7. In the text box, paste the text you just copied.
   8. Click the menu icon to the right of the "SAVE" button and click "Switch to editor mode".
   9. For each item in the list, replace the items on the RIGHT side of the list with equivalent words and phrases in your language.
      • What ever you do, DO NOT change the values on the left side of the list. Nightscout will be looking for these exact values. Only change the items on the right side of the list.
   10. Click the "SAVE" button.
10. You should be good to go! Feel free to try it out by click the "See how it works in Google Assistant" link in the right navigation pane, or start asking your Google-Home-enabled device some questions. See Interacting with Virtual Assistants for details on what you can do with Google Home.

Adding Google Home support to a plugin

See Adding Virtual Assistant Support to a Plugin