Adding VoiceInsights to an Alexa Skill

One of my goals for 2017 is to not just write more Alexa Skills, but make sure what I'm creating is of top quality. Part of the challenge is how to add instrumentation to the application so you can see how actual users are interacting with the skill. I've tried out different patterns from this including writing out to DynamoDB tables and then analyzing in Excel. Fortunately the ecosystem is growing around Voice platforms, and there are some start-ups providing services around Alexa. I tried out one, and here's what I was able to do with it. Seems like a promising tool, and right now their base product is free.

Step 1 - Sign-up for VoiceLabs account

Start by signing up for a free account at VoiceLabs.co. It's minimal information to get started, and doesn't require a credit card or other fees.

Then setup an application within the console.

This will give you an API Key required to call the service from your skill.

Step 2 - Create a Deployment Pipeline for Lambda

If you typically use the browser-based IDE for Lambda, you're going to need to spend some time setting up a build pipeline to include the Voice Insight SDK into your skill. If you already have this, go ahead and skip this step.

First, start by deploying a new EC2 instance with Bitnami node js AMI through the console or API's. Here's the specific AMI you will need:

bitnami-nodejs-7.2.1-0-linux-ubuntu-14.04.3-x86_64-ebs-mp-07a06354-51d6-4394-9cbc-aa37efb4b54f-ami-50a6a747.3 (ami-ee07b78e) 

The AMI doesn't include PIP, so you'll also need that step.

curl "https://bootstrap.pypa.io/get-pip.py" -o "get-pip.py"
sudo python get-pip.py

Next go ahead and install the AWS CLI to the instance by first running the following command.

 sudo pip install awscli

Once that is done, go into your AWS account and using IAM, create a user account that has full access to the S3 service.

Go through the four steps, and once completed it will give you an access key ID and secret access key. Record those, and from the command line, configure the AWS CLI using them.

aws configure
AWS Access Key ID [None]: 
AWS Access Key ID [None]: <your key here>
AWS Secret Access Key [None]: <your secret key here>
Default region name [None]: 

That's it, and you can now reuse this process or the instance itself later when needed.

Step 3 - Configure your skill to use Voice Analytics

First, on the build server created in the previous step, use npm to install the Voice Insights SDK through the following command.

npm install voice-insights-sdk --save

Then, within your skill, include a reference to it, along with the application key that was generated in the first step.

var APP_ID = 'amzn1.ask.skill.<change to your skill id>'; 
var VoiceInsights =require('voice-insights-sdk'), 
 VI_APP_TOKEN = '<this is the token created in step 1>';  

Next, find where the session initiates in your skill, and add the following statement.

VoiceInsights.initialize(session, VI_APP_TOKEN); 

Finally, in each intent you want to record activity, add the following logic.

       
VoiceInsights.track('WelcomeMessage', {}, speechOutput.speech, (err, res) => {
    callback(sessionAttributes,
        buildSpeechletResponse(CARD_TITLE, speechOutput, repromptText, shouldEndSession));
});

More examples are given in in the VoiceLabs console for reference, including different options on the attributes that are passed into the call, as well as how this works in other languages like Java and Ruby.

Attached to the bottom of this story is a GitHub repo that shows all of this in context for the code for reference.

Step 4 - Deploy to a Staging Area

Now we need to take the package from the EC2 instance, and put it someplace that can get picked up by the Lambda function. The easiest way is to create a package, then stage it to the data object service in AWS called S3. If you don't already have an S3 bucket to use, go ahead in the console and create one. Here's a screenshot in the AWS console for reference - just pick a unique name, and an AWS Region to deploy it into.

First, make sure that you have the code for your skill saved locally on the build server. I'm using the file name "lambda.js" for reference. It should be in the same directory that we installed the Voice Insights SDK from the prior step. When you're ready to create the package, just create a zip file with all of the necessary files.

zip -r trivia.zip lambda.js node_modules/

We're including the "-r" option in the zip command so that it picks up the dependent node libraries, including the voice-labs one that we installed in step 3. That gives us a build package, then execute this CLI command to push the package out to an S3 bucket.

aws s3 cp trivia.zip s3://<your bucket name here>/ 

This acts like a local Linux copy command that can then push out the zip file to the S3 bucket. If you are having problems with this step, check the credentials that were setup in step 2 as they might not have full access to S3.

Step 5 - Activate Staging Environment

Within the lambda options for deploying the skill, choose "Upload a file from Amazon S3." You can also do this within the CLI if you want to fully automate the pipeline, but I'd rather have this manual for now so I don't inadvertently push a new release out.

Once this step is complete, your build package replaces whatever previously was in the browser based IDE.

Step 6 - Analyze Results

Once you've integrated this into the skill, the analytics engine from Voicelabs processes the data. There are a couple of different useful views within the product, starting with a trend over time of the broad usage of the skill. This differs from what's in the Amazon console as it provides it in real time (the Amazon console normally has a 24-48 hour lag) and it breaks out sessions vs. users.

There are also more in-depth views of the skill usage, going into how what intent is being used the most, and how long the sessions are held for. No real equivalent to this in the Amazon console.

If you're looking for how each user has used the skill, that's all tracked. The VoiceInsights tool creates a proxy user account for each that matches what the device is passing in (sort of like a MAC address for the account).

There's also a way to track the flow of the session, and see how different paths are being taken.

Conclusion

This is a great measurement tool to record actual user data, and a huge step up from what is available from the console. It's just a few extra lines of code and FREE!