Configuring Voice Assistants

Voice Assistant Integration

Any smart home IoT system is not complete without Voice Assistant integrations. ESP RainMaker supports integration with Amazon Alexa and Google Voice Assistant (GVA), allowing users to control their IoT devices using voice commands.

This section covers native code level configurations required on the iOS and Android ESP RainMaker Home App to integrate with the supported voice assistants.

Android Code Level Configurations

Alexa Account Linking

This account linking flow enables users to link their Alexa user account with their account in another service by starting from the app. The following sections cover the app side configuration for Alexa account linking.

note

For more information on account linking and the cloud configuration, please go here.

Creating Android App Links

In Alexa account linking process, we need to allow the Alexa app or browser to redirect the user to your app. To allow this redirection, you must enable App Links for your Android app.

Please check Android documentation to enable App Links in Create Deep Links to App Content and in Verify App Links.

Here are the steps for creating and configuring App Link for your Android app which uses ESP RainMaker deployment.

1. Create App Link for ESP RainMaker deployment using these steps and take redirectURL which is created from those steps (you will get redirectURL from step-12).

2. Follow below steps to create assetlinks.json file.

   1. Download this assetlinks.json file.
   2. Write your application ID in place of your_application_id.
   3. Add your sha256_cert_fingerprint of your keystore file in place of add_your_sha256_fingerprint_here in JSON array.
   note

   • If you don't have keystore for App Signing, please create using these steps.
   • Run ./gradlew signingReport command to get SHA-256 fingerprint.
   • To make App Link work, you need to install app with same signing for which SHA-256 fingerprint added.

3. Upload assetlinks.json file in .well-known folder using these steps.

4. Modify host value in data tag of AlexaAppLinkingActivity in AndroidManifest.xml file. You can get host value by removing "https://" from your redirectURL and add it in place of your_host_value in AndroidManifest.xml file.

Here is the example of Android App Link setup.

1. Let's assume you have followed 1st step and got redirectURL as below.

   https://my-app-link.s3.amazonaws.com/

2. Download assetlinks.json file. Replace your_application_id with com.example.my_app which is an application ID of the Android app. After that run ./gradlew signingReport command and get SHA-256 fingerprint and add it in file.

   After these changes assetlinks.json file looks as below.

   [{
     "relation": ["delegate_permission/common.handle_all_urls"],
     "target": {
       "namespace": "android_app",
       "package_name": "com.example.my_app",
       "sha256_cert_fingerprints":[
           "E6:B5:DD:AF:62:90:93:3E:63:52:6B:C6:15:CC:DC:A3:1E:DE:AF:20:D2:07:3F:A4:89:CB:8C:78:D2:AE:CC:0D"
       ]
     }
   }]

3. Upload assetlinks.json file in .well-known folder.

4. Replace your_host_value with your host value from redirect URL in AndroidManifest.xml as below.

   <activity
       android:name="com.espressif.ui.activities.AlexaAppLinkingActivity"
       android:label="@string/title_activity_amazon_alexa"
       android:launchMode="singleTask"
       android:screenOrientation="portrait"
       android:theme="@style/AppTheme.NoActionBar">
       
       <intent-filter android:autoVerify="true">
           <action android:name="android.intent.action.VIEW" />
           
           <category android:name="android.intent.category.DEFAULT" />
           <category android:name="android.intent.category.BROWSABLE" />
           
           <data
               android:host="my-app-link.s3.amazonaws.com"
               android:scheme="https" />
       </intent-filter>
   </activity>

note

You can also use Digital Asset Links Generator or the App Links Assistant in Android Studio to create Android App Links and test links.

Configuring Account Linking

All the configuration parameters for Alexa account linking can be set from local.properties file.

Open the project in Android Studio and local.properties file will be generated. Please add values for following configuration fields.

Configuration key	Type	Description
authUrl	String	OAuth URL. To get this value please see here.
alexaClientId	String	Alexa client ID. This can be found in: - Go to Alexa dev console - Click your skill - Go to the Build tab - Go to Permissions section - Under Permissions the Alexa Client ID can be found.
alexaClientSecret	String	Alexa client secret. This can be found in: - Go to Alexa dev console - Click your skill - Go to the Build tab - Go to Permissions section - Under Permissions the Alexa Client Secret can be found.
alexaRedirectUrl	String	Redirect URL is provided in the calls to get Alexa authorization code and RainMaker (or custom user authorization service) authorization code. This is also used as the App Link for the Android app. In order to find out how to configure App Link, please check this.
alexaRMClientId	String	Refer to Steps to get Alexa and GVA client ID and copy the esp-rainmaker-alexa-skill client id
skillId	String	Skill ID of skill to be linked. This can be found in: - Go to Alexa dev console - Click your skill - Go to Build tab - Go to Smart Home section - Under Smart Home section, Skill ID can be found.
skillStage	String	Possible values: live: for live skill development: for a skill under development.
alexaAccessTokenUrl	String	API endpoint used to fetch Alexa access token from Alexa authorization code. Check link for steps to get the value of the Alexa access token URL.

iOS Code Level Configurations

Alexa Account Linking

This account linking flow enables users to link their Alexa user account with their account in another service by starting from the app. The following sections cover the app side configuration for Alexa account linking.

note

For more information on account linking and the cloud configuration please go here.

Creating iOS Universal Links

When you support universal links, iOS users can tap a link to your website and get seamlessly redirected to your installed app without going through Safari. If your app isn't installed, tapping a link to your website opens your website in Safari.

Please check iOS documentation for Universal Links.

You can go through the following steps in order to create a universal link for your app:

1. In your app's Xcode project select the .xcodeproj file in the project navigator. In the Signing and Capabilities section, there is an Associated Domains section. Click the + sign in the Domains section. Add the following information in that section:

   applinks:domain name of the associated website

2. Create a file named apple-app-site-association. This file will contain the following JSON structure:

       {
       "applinks": {
       "apps": [],
           "details": [
           {
               "appID": "ABCD1234.com.apple.wwdc",
               "paths": ["*"]
           }
           ]
       }
       }
   note

   Do not add .json to the apple-app-site-association file.

3. The appID in the above file has the following format: TEAMID.Bundle ID of your app.

   Find more information on Team ID here and more information on app Bundle ID here.

4. The paths array contains the list of paths for your website for which the app supports universal links. The * value for paths means that all possible paths for your website are supported.

5. This apple-app-site-association file has to be placed in the root directory of your server or in the .well-known folder in the root directory of your server.

6. The file needs to be accessible via HTTPS—without any redirects—at https://<domain>/apple-app-site-association or https://<domain>/.well-known/apple-app-site-association.

Configuring Account Linking

In the Configuration.plist file, under the AWS Configuration section please ensure the following value is added:

Key	Type	Description
Authentication URL	String	OAuth URL. To get this value please see here.

In the Configuration.plist file, under the ESP Alexa Configuration section the following values need to be added:

Key	Type	Description
Alexa Client Id	String	Alexa client ID. This can be found in: - Go to Alexa dev console. - Click your skill - Go to Build tab - Go to Permissions section - Under Permissions the Alexa Client Id can be found.
Alexa Client Secret	String	Alexa client secret. This can be found in: - Go to Alexa dev console. - Click your skill - Go to build tab - Go to Permissions section - Under Permissions the Alexa Client Secret can be found.
Alexa RM Client Id	String	Refer to Steps to get Alexa and GVA client ID and copy the esp-rainmaker-alexa-skill client id
Skill Id	String	Skill ID of skill to be linked. This can be found in: - Go to Alexa dev console. - Click your skill - Go to Smart Home section, where the Skill Id can be found.
Skill Stage	String	Possible value: live: for live skill development: for a skill under development.
Redirect URL	String	This URL is provided in the calls to get Alexa auth code and RainMaker (or custom user auth service) auth code. This is also used as the universal link for the iOS app. In order to find out how to configure universal link, please check this link.
Alexa Access Token URL	String	API endpoint used to fetch Alexa access token from Alexa auth code. Check link for steps to get the value of the Alexa Access Token URL.