About

This is the VoiceLabs SDK.

VoiceInsights provides all Alexa developers powerful insights and tools to understand voice patterns, re-engage at-risk users, and build more compelling voice experiences.

Get started at http://www.voicelabs.co

Getting started

Before you get started, you'll need an application token. Feel free to head over to http://insights.voicelabs.co/getstarted to create your analytics account and get your application token.

Typical integrations take less than 10 minutes, from account creation to seeing events in your analytics dashboard.

The Voice Insights SDK is dead simple and compatible with all popular Node.js Alexa frameworks:

• The original Alexa Skills Kit: https://github.com/amzn/alexa-skills-kit-js
• The new Alexa Skills Kit: https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs
• The alexa-app framework: https://www.npmjs.com/package/alexa-app

End User Docs

For detailed usage information and framework-specific API docs, head out here: http://insights.voicelabs.co/getstarted

Create your free analytics account and go to the docs section for more details: http://insights.voicelabs.co/analytics#/settings/docs

Getting help

If you need help installing or using the library, please contact VoiceLabs Support at [email protected] first. VoiceLabs' customer success team is well-versed in everything related to the SDK, and will reply within 24 hours.

If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!

Quick Example

The below is an example using the original Alexa Skills Kit.

Initializing

If you've already integrated with a previous version of the SDK, first uninstall it:

npm uninstall voice-insights-sdk --save

Then within your Alexa src/ folder, issue the following command:

npm install voicelabs --save

Note that if uploading to Lambda, it will automatically look for your node dependencies inside the node_modules folder created by installing this SDK.

Once you've installed the module, you can initialize VoiceLabs and start tracking events:

var APP_ID = 'amzn1.echo-sdk-ams.app.********-****-****-****-************';
...

var VoiceLabs = require("voicelabs")('<your-app-token>');

Tracking usage

Note that several of the parameters passed in are optional, but highly recommended to get the most out of your skill's analytics:

/**
   * Fires a track event to capture user speech, and agent speech
   * Always executes the callback if provided, and returns a Promise if needed
   *
   * @param  {Object}   session             Alexa Session Object (to get userId and SessionId)
   * @param  {String}   intentName          The intent string
   * @param  {Object}   intentMetadata      (Optional) Object containing intent metadata like slots
   * @param  {String}   speechText          (Optional) String speech out by Alexa
   * @param  {Function} callbackFn          (optional) Callback function for success, always gets called
   * @return {Promise}
   */
track: function(session, intentName, intentMetadata, speechText, callbackFn)

NOTE: the callbackFn or your Promise.then() must encapsulate your response back to Alexa for the track event to go through consistently.

You can track events by simply adding this single line when handling intent requests (or other types of requests):

var newSessionHandlers = {
    'NewSession': function() {
        ...

        var speechText = "Hello, and welcome!";

        VoiceLabs.track(this.event.session, intent.name, intent.slots, speechText, (error, response) => {
          this.emit(':tell', speechText);
        });
    }
};

If you have extensive business logic and a large existing codebase with lots of intents, you can use promises to integrate in a more flexible manner:

var self = this;

VoiceLabs.track(this.event.session, 'NewSession', null, "Welcome to High Low Guessing game")
          .then(function(){
            self.emit(':ask', 'Welcome to High Low guessing game. would you like to play?',
                'Say yes to start the game or no to quit.');
          });