[中文版本]

Overview

This guide covers the deployment of 3P-Integration stacks to integrate Alexa and Google Voice Assistants with RainMaker using AWS SAM and CloudFormation StackSets. Key integrations include Cognito App Clients for Alexa and Google, Lambda functions for voice assistant directives, and essential add-ons for certification requirements.

Component Description

The deployment consists of the following stacks:

1. AWS Cognito App Clients for Alexa and Google Voice Assistant (ESP-RainMaker-3p-CognitoClients)

   • Creates AWS Cognito App Clients for the Alexa Skill and Google Actions.

2. Alexa Smart Home Skill and Google Smart Home Action in 3 regions (ESP-RainMaker-3P-Integrations)

   • Deploys Lambda functions that handle directives from Alexa and Google Voice Assistant.

3. Alexa Smart Home Skill and Google Action AddOn Extension

   • Google Actions: The add-ons repository provides a webhook handler that proactively reports node state changes to Google's Home Graph database. For more information, see Google Smart Home Action Report State. Proactive reporting is required for certifying your Google action.

   • Alexa Skills: The add-ons repository provides API endpoints required for Alexa App-to-App account linking. This feature enables account linking starting from your app. For more information, see Alexa App-to-App Account Linking. Implementing App-to-App account linking is required for obtaining Works with Alexa (WWA) certification for your product (WWA certification is separate from Alexa skill certification and publication).

   • For both Alexa and Google Action certification, these functionalities are necessary, making it essential to deploy this repository.

Prerequisites

ESP-RainMaker-3p-CognitoClients

1. Ensure that you have created a Cognito domain using the steps provided in Cognito Domain Configurations.

2. Note down the Identity Providers:
   • Access the RainMaker Dashboard and click on the Deployment Settings tab in the left navigation bar
   • Click on the Identity Providers tab
   • Record the configured Identity Providers
   • If Google, GitHub, and SignInWithApple are configured, the corresponding values in SkillIdentityProviders when deploying ESP-RainMaker-3p-CognitoClients will be Google, GitHub, SignInWithApple, COGNITO

Note: If no identity provider is configured, the default value will be set to only COGNITO.

3. Note down the AlexaCognitoCallbackURLs and SkillId as described in the Alexa skill creation step.

4. Note down the GVACallbackURLs as described in the Google Action creation step.

ESP-RainMaker-3P-Integrations

• Alexa and Google Voice Assistant handlers call the RainMaker API endpoint URL for device information. Therefore, you need to provide the RainMaker API URL as input to the ESP-RainMaker-3P-Integrations Application.
• Follow the Get Base URL steps to fetch the RainmakerAPIUrl.
• RainMaker Backend API Endpoint URL: <RainmakerAPIUrl>/v1/
• Note this value, as you will need it as the APIEndPointURL in the next step.

Google Voice Assistant: Enabling Google Asynchronous Messaging and Getting Google Messaging Client Details

Google Voice Assistant requires the handler to report state to the Homegraph service in Google Cloud. Therefore, you need to create and add Google Service Account credentials to the handler.

If you want to deploy Google Action integration, follow these steps to obtain the credentials:

1. Enable the Homegraph API in your account:

   • Visit the Google Homegraph page
   • Select your smart home project from the drop-down menu at the top
   • Click Enable

2. Create a Service Account Key file:

   • Go to the Google Service Account page
   • Select your smart home project
   • Click "Create Service Account"
   • Enter a suitable name in the Service Account Name field
   • Add "Service Account for report state token creation" in the description
   • Click Create and Continue
   • Select the role type "Service Accounts" and choose "Service Account token creator"
   • Click Continue and then Done
   • Click on the created service account email
   • Go to the Keys option and click Add Key
   • Select "Create Key"
   • Choose JSON key type
   • Download the credentials file
   • Open the downloaded service account file and note down these values:
     • GVAClientID (client_id)
     • GVAClientEmail (client_email)
     • GVAPrivateKey (private_key)
     • GVAPrivateKeyID (private_key_id)
     • GVAProjectID (project_id)

Alexa Skills: Enabling Alexa Asynchronous Messaging and Getting Alexa Messaging Client Details

For Works with Alexa certification, you must report device state to Alexa. This requires enabling Asynchronous messaging.

If you want to deploy Alexa skills integration, enable Alexa Asynchronous messages and obtain the AlexaClientId and AlexaClientSecret:

1. Log in to the Alexa Developer Console

2. Select your smart home skill

3. Go to the "Permissions" tab in the left navigation bar and enable "Send Alexa Events"

4. After enabling "Send Alexa Events", you'll see a new "Alexa Skill Messaging" section

5. Note down the Alexa Client Id and Alexa Client Secret values

Deployment Steps

To deploy the Alexa and Google Voice Assistant integration components, we'll use CloudFormation multi-region stackset. This will deploy:

• ESP-RainMaker-3p-CognitoClients
• ESP_RainMaker-3P-Integrations-Addons
• ESP-RainMaker-3P-Integrations (in regions: us-east-1, eu-west-1, us-west-2)

1. Access AWS Management Console

   • Search for CloudFormation in the Services menu and select it

   

2. Create a Stackset

   • Click "Create stackset" in CloudFormation

   

3. Select IAM Roles

   • The required IAM roles will be created automatically
   • Choose the appropriate roles and click "Next" Admin Role: esp-AWSCloudFormationStackSetAdminRole Execution Role: esp-AWSCloudFormationStackSetExecutionRole

   

4. Select Template

   • Construct the S3 URL Template using the guide here

   

5. Enter Stack Name

   • Enter ESP-3P-Integrations-Skills-Add-Ons as the stack name

   

6. Enter Input Parameters

   • Provide the required parameters for Alexa and Google Voice Assistant integration
   • Refer to their respective module sections for descriptions

   

   • Click "Next"

   Parameter Name	Description
   AlexaCognitoCallBackUrls	Find this value in Create an Alexa Smart Home Skill
   GVACognitoCallBackUrls	Find this value in Create a Google Smart Home Action
   SkillIdentityProvidersNewUserPool	Enter the identity providers noted in Creating AWS Cognito App Clients for Alexa and Google Voice Assistant
   SkillIdentityProviders	Keep default values. For configured providers (Google, GitHub, SignInWithApple), values will be Google, GitHub, SignInWithApple, COGNITO
   APIEndPointURL	The RainMaker Backend API Endpoint URL from Getting the API Endpoint URL
   AlexaClientID	Alexa Client ID for obtaining Alexa refresh tokens
   AlexaClientSecret	Alexa Client Secret noted earlier
   AlexaSkillID	Your Alexa skill ID
   RainMakerRegion	Region where RainMaker is deployed (e.g., us-east-1)
   ManufacturerName	Your product's manufacturer name (visible for all scenes and products)
   ProductDescription	Your product's description
   SceneDescription	Description for scenes associated with your product
   GVAClientID	Google Client ID from Service Account
   GVAClientEmail	Google Client Email from Service Account
   GVAPrivateKey	Google Private Key from Service Account
   GVAPrivateKeyID	Google Private Key ID from Service Account
   GVAProjectID	Google Project ID from Service Account

7. Add Tags

   • Add a version tag:
     • Key: Version
     • Value: <VERSION> (use your selected version)
   • Click "Add new tag" and keep other defaults
   • Click "Next"

   

8. Configure Account and Regions

   • Enter your Account ID
   • Select these regions for Alexa's multi-region deployment:
     • US East 1 (N. Virginia)
     • US West 2 (Oregon)
     • EU West 1 (Ireland)
   • If your RainMaker region differs, select it as well

   

9. Review and Create

   • Acknowledge the following:
     • AWS CloudFormation might create IAM resources
     • AWS CloudFormation might create IAM resources with custom names
     • AWS CloudFormation might require CAPABILITY_AUTO_EXPAND
   • Click "Create stackset"

   

10. Wait for Completion

    • Allow approximately 15-20 minutes for the stackset to deploy in all selected regions