@voxalyze/skill-sdk

Voxalyze SDK for Alexa Skills

With Voxalyze, you can get real-time reports and insights about your Alexa skill visitors on multiple dimensions. This SDK reports meta-data from your Alexa Skill to our API. We match the data received from your skill with data we collect through our campaign proxy. This allows us to track where your visitors come from and which of your campaigns perform best.

Contents

• Contents
• Installation
• Setup
  • Setting your API key
  • Tracking data with your ASK based skill
    • Individually wrapping handler in the addRequestHandlers arguments
    • Wrapping a list of handlers in addRequestHandlers arguments
    • Wrapping a single handler function in the addRequestHandler arguments
  • Tracking data for skills without ASK
• Error handling
• Privacy and compliance
• Debugging

Installation

To use the Voxalyze Skill SDK, first install it with npm or yarn:

$ npm install @voxalyze/skill-sdk

Setup

The Voxalyze Skill SDK supports both plain Lambda function and handlers you define for the ASK SDK. To get campaign attribution data, you should at least track your LaunchRequest handler. More information about about request types can be found in the Alexa developer documentation.

Setting your API key

To get started, head to your Voxalyze account and create a new API key. Make sure the API key is available in the environment variables for your skill under the name VXL_APIKEY.

Important: Setting API keys when deploying with ASK CLI

Setting environment variables is currently not possible if you deploy directly with the ASK CLI. In this case, you can either manually add the environment variable to your Lambda after it is deployed or override the API key by mutating the SDK config directly (before you call any other Voxalyze function):

Voxalyze.config.init({
  apiKey: '<YOUR_API_KEY>',
});

While we do not recommend having API keys in your code, there is not fundamental security threat in this case due to the fact that your API keys can only send event reports, but cannot be used to access data from your account.

Tracking data with your ASK based skill

The Voxalyze Skill SDK supports different ways to track your handlers. You can find the three different alternatives listed below.

Individually wrapping handler in the addRequestHandlers arguments

const Alexa = require('ask-sdk');
const Voxalyze = require('@voxalyze/skill-sdk');

Voxalyze.config.init({
  apiKey: '<YOUR_API_KEY>',
});

const skillBuilder = Alexa.SkillBuilders.standard();

module.exports.handler = skillBuilder
  .addRequestHandlers(
    Voxalyze.track(LaunchRequest),
    Voxalyze.track(NameIntent),
    HelpIntent,
    CancelOrStopIntent,
    SessionEndedRequest,
    FallbackIntent
  )
  .lambda();

Please be aware, that the tracker will not track function calls from the registered handler to another handler. So if you would manually call the NameIntent handler in our example from the HelpIntent handler, no data would be sent to Voxalyze since the sub-handler invocation was not wrapped by our tracker.

Wrapping a list of handlers in addRequestHandlers arguments

Simply wrap all or as many handlers as you want in your addRequestHandlers arguments.

const Alexa = require('ask-sdk');
const Voxalyze = require('@voxalyze/skill-sdk');

Voxalyze.config.init({
  apiKey: '<YOUR_API_KEY>',
});

const skillBuilder = Alexa.SkillBuilders.standard();

module.exports.handler = skillBuilder
  .addRequestHandlers(
    ...Voxalyze.track(
      LaunchRequest,
      NameIntent,
      HelpIntent,
      CancelOrStopIntent
    ),
    SessionEndedRequest,
    FallbackIntent
  )
  .lambda();

Wrapping a single handler function in the addRequestHandler arguments

If you add your request handler with the addRequestHandler method, you can simply wrap your handler function in the Voxalyze tracker.

const Alexa = require('ask-sdk');
const Voxalyze = require('@voxalyze/skill-sdk');

Voxalyze.config.init({
  apiKey: '<YOUR_API_KEY>',
});

const skillBuilder = Alexa.SkillBuilders.standard();

module.exports.handler = skillBuilder
  .addRequestHandler(matcher, Voxalyze.track(handler))
  .lambda();

Tracking data for skills without ASK

If you don't use the ASK-SDK, you can also wrap your plain Lambda handler function with the Voxalyze SDK.

const Voxalyze = require('@voxalyze/skill-sdk');

async function skillHandler(event, context) {
  // ...do something
}

module.exports.handler = Voxalyze.trackLambda(skillHandler);

In case you only want to track some specific invocations, simply add a proxy function that selects the handler your want to invoke for a specifc request type (e.g. LaunchRequest).

const Voxalyze = require('@voxalyze/skill-sdk');

async function launchRequestHandler(event, context) {
  // ...do something
}

async function proxyHandler(event, context) {
  switch (event.request.type) {
    case 'LaunchRequest':
      return Voxalyze.trackLambda(launchRequestHandler);
    default:
      return otherHandler(event, context);
  }
}

module.exports.handler = proxyHandler;

Error handling

The Voxalize Skill SDK will not block the execution of your skill code. If there is an error occurring in the SDK, it will be logged but not thrown.

Privacy and compliance

The Voxalyze Skill SDK does not send any personally identifiable information (PII) to our servers. You are free to choose what handlers you want to track. Although you need to track at least the LaunchRequest handler to receive meaningful campaign attribution data. Below you can find an exact overview what data we collect through this SDK.

Field	Description
eventId	A random ID, generated by the SDK for each event
skillId	The unique ID of your Alexa skill
userId	The user ID for your skill user. This is no PII since the ID is unique per user/skill and gets regenerated everytime the user re-installs your skill
deviceId	The device ID for your skill user's device. This is no PII since the ID is unique per user/skill and gets regenerated everytime the user re-installs your skill
viewport	Data on the device's screen type and sizes
requestType	The type of request, e.g. 'LaunchRequest'
requestId	The Amazon request ID. Useful for tracing and error handling
locale	The device's locale, e.g. 'de-DE'
timestamp	A timestamp when the event was triggered

Debugging

We use the debug package for debug log output. If you experience any issues, we recommend testing your skill handlers locally while activating the SDK's debug output:

$ DEBUG=voxalyze-sdk:* node index.js

Or on Windows:

> set DEBUG=voxalyze-sdk:* & node index.js