Welcome to the Alexa documentation for Dimension! Integrating Dimension into your Alexa skill is quick and easy.

Select Amazon Alexa on the left and choose the option that best matches your environment.

If you have any questions, comments, or suggestions, please feel free to contact us.

Lambda Integration with Skills SDK v2 and NPM

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dimension via NPM

npm install --save dimensionlabs

Include Dimension and use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).alexa;

Wrap your handler in the Dimension handler call

before:

exports.handler = skillBuilder
  .addRequestHandlers(
    LaunchRequestHandler,
    ...
    HelpIntentHandler,
    CancelAndStopIntentHandler,
    SessionEndedRequestHandler
  )
  .addErrorHandlers(ErrorHandler)
  .lambda();

after:

exports.handler = dimension.handler(
  skillBuilder
  .addRequestHandlers(
    LaunchRequestHandler,
    ...
    HelpIntentHandler,
    CancelAndStopIntentHandler,
    SessionEndedRequestHandler
  )
  .addErrorHandlers(ErrorHandler)
  .lambda()
);

You’re all set!

Example

Using the Alexa Skills Kit SDK for Node.js and AWS Lambda, it is easy to integrate Dimension.

We have added Dimension to these three sample Alexa Skills:

Lambda Integration with Skills SDK and NPM

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dimension via NPM

npm install --save dimensionlabs

Include Dimension. Use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).alexa;

Wrap your handler in the Dimension handler call

before:

exports.handler = (event, context, callback) => {
  const alexa = Alexa.handler(event, context);
  alexa.appId = APP_ID;
  alexa.resources = languageString;
  alexa.registerHandlers(newSessionHandlers, startStateHandlers, triviaStateHandlers, helpStateHandlers);
    alexa.execute();
};

after:

exports.handler = dimension.handler(
  (event, context, callback) => {
    const alexa = Alexa.handler(event, context);
    alexa.appId = APP_ID;
    alexa.resources = languageString;
    alexa.registerHandlers(newSessionHandlers, startStateHandlers, triviaStateHandlers, helpStateHandlers);
    alexa.execute();
  }
);

You’re all set!

Example

Using the Alexa Skills Kit SDK for Node.js and AWS Lambda, it is easy to integrate Dimension.

We have added Dimension to these three sample Alexa Skills:

Alexa Webhook Integration with NPM

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dimension via NPM

npm install --save dimensionlabs

Include Dimension

Use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).alexa;

Log whenever your webhook is called, and whenever you send a response

app.use(bodyParser.json())
...
app.post('/alexa', (req, res) => {
  dimension.logIncoming(req.body);
  ...
  const responseBody = {
    'version': '1.0',
    'response': {
      'outputSpeech': {
        'type': 'PlainText',
        'text': 'Hello World!'
      },
      'card': {
        'content': 'Hello World!',
        'title': 'Hello World',
        'type': 'Simple'
      },
      'shouldEndSession': true
    },
    'sessionAttributes': {}
  };
  dimension.logOutgoing(req.body, responseBody);
  res.send(responseBody);
}

Example

View a sample.

Sending outbound Intents (optional)

Optionally send outbound Intents to be able to rollup messages based on the response.

Add the Intent to the responseBody

app.use(bodyParser.json())
...
app.post('/alexa', function(req, res) {
  dimension.logIncoming(req.body);
  ...
  const responseBody = {
    'intent': {
       'name' : 'WEATHER_RESPONSE',
       'inputs' : [
         {
           'name': 'forecast',
           'value': '68 and sunny',
         }
       ]
     },
    'version': '1.0',
    'response': {
      'outputSpeech': {
        'type': 'PlainText',
        'text': 'Hello World!'
      },
      'card': {
        'content': 'Hello World!',
        'title': 'Hello World',
        'type': 'Simple'
      },
      'shouldEndSession': true
    },
    'sessionAttributes': {}
  };
  dimension.logOutgoing(req.body, responseBody);
  res.send(responseBody);
}

Ruby Gem

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dimension Ruby Gem

gem install dimension

Initialize Dimension

Use the API key created above.

@appToken = process.env.DIMENSION_API_KEY
@dba = Dimension::DimensionSDK.new(appToken, requestBody['session'])

Re-initialize on new session (user)

Use the API key created above.

@dba = Dimension::DimensionSDK.new(appToken, requestBody['session'])

Track requests

@vi.track(requestBody['request']['intent']['name'] , requestBody['request'], response.build_response)

Python SDK

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dimension Python SDK

pip install dimension

Import the Dimension library

from dimension import alexa

Initialize Dimension

Use the API key created above.

dba = alexa.alexa(os.environ.get(DIMENSION_API_KEY))

Notice in this example, you set the environment variable DIMENSION_API_KEY to your api key.

Log incoming requests

dba.logIncoming(incomingRequest)

Log outgoing response

Pass both the incoming request and the response

dba.logOutgoing(incomingRequest, response)

Alexa Python SDK (with Flask)

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dimension Python SDK

pip install dimension

Import the Dimension library

from dimension import alexa

Initialize Dimension

Use the API key created above.

dba = alexa.alexa(os.environ.get('DIMENSION_API_KEY'))

Notice in this example, you set the environment variable DIMENSION_API_KEY to your api key.

Create the Global Request & Response Interceptors

from ask_sdk_core.serialize import DefaultSerializer

ds=DefaultSerializer()

@sb.global_request_interceptor()
def request_logger(handler_input):
    serializedRequest=ds.serialize(handler_input.request_envelope)
    dba.logIncoming(serializedRequest)

@sb.global_response_interceptor()
def response_logger(handler_input, response):
    serializedRequest=ds.serialize(handler_input.request_envelope)
    serializedResponse=ds.serialize(response)
    dba.logOutgoing(serializedRequest,serializedResponse)

REST API

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

There are two integration points as outlined below.

1. When Alexa posts to your webhook endpoint

When Alexa posts to your webhook endpoint, post the same data Alexa sent to you to the following endpoint:

https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=incoming&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and replace API_KEY_HERE with your api key.

The data to POST should pass the following data:

{
  "event": {
    "version": "1.0",
    "session": {
      "new": false,
      "sessionId": "amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef",
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"
      },
      "attributes": {},
      "user": {
        "userId": "amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"
      }
    },
    "request": {
      "type": "IntentRequest",
      "requestId": "amzn1.echo-api.request.123123a-733e-4e89-893a-fdcb77e2ef0d",
      "timestamp": "2015-05-13T12:34:56Z",
      "intent": {
        "name": "airportinfo",
        "slots": {
          "AIRPORTCODE": {
            "value": "JFK",
            "name": "AIRPORTCODE"
          }
        }
      }
    }
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"event":{"version":"1.0","session":{"new":false,"sessionId":"amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef","application":{"applicationId":"amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"},"attributes":{},"user":{"userId":"amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"}},"request":{"type":"IntentRequest","requestId":"amzn1.echo-api.request.123123a-733e-4e89-893a-fdcb77e2ef0d","timestamp":"2015-05-13T12:34:56Z","intent":{"name":"airportinfo","slots":{"AIRPORTCODE":{"value":"JFK","name":"AIRPORTCODE"}}}}}}'
     'https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=incoming&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE with your api key.

Note
This is just an example — we accept any rich media that Alexa accepts.

2. When your Skill sends a message

When your bot sends a message, POST to the following endpoint:

https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and replace the API_KEY_HERE placeholder with your api key.

The data to POST should pass the following data:

{
  "event": {
    "version": "1.0",
    "session": {
      "new": false,
      "sessionId": "amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef",
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"
      },
      "attributes": {},
      "user": {
        "userId": "amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"
      }
    },
    "request": {
      "type": "IntentRequest",
      "requestId": "amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d",
      "timestamp": "2015-05-13T12:34:56Z",
      "intent": {
        "name": "airportinfo",
        "slots": {
          "AIRPORTCODE": {
            "value": "JFK",
            "name": "AIRPORTCODE"
          }
        }
      }
    }
  },
  "response": {
    "version": "1.0",
    "sessionAttributes": {},
    "response": {
      "shouldEndSession": true,
      "outputSpeech": {
        "type": "SSML",
        "ssml": "<speak>The weather at JFK is 68 and sunny.</speak>"
      }
    }
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"event":{"version":"1.0","session":{"new":false,"sessionId":"amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef","application":{"applicationId":"amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"},"attributes":{},"user":{"userId":"amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"}},"request":{"type":"IntentRequest","requestId":"amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d","timestamp":"2015-05-13T12:34:56Z","intent":{"name":"airportinfo","slots":{"AIRPORTCODE":{"value":"JFK","name":"AIRPORTCODE"}}}}},"response":{"version":"1.0","sessionAttributes":{},"response":{"shouldEndSession":true,"outputSpeech":{"type":"SSML","ssml":"The weather at JFK is 68 and sunny."}}}}'
     'https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE with your api key.

Note
This is just an example — we accept any rich media that Alexa accepts.

3. Outbound Intents (Optional)

With Intents, you can roll up similar messages your bot sends to quickly see the combined metrics.

Define Intent

{
  "name": "WEATHER_RESPONSE",
  "inputs": [
    {
      "name": "forecast",
      "value": "68 and sunny"
    }
  ]
}

Append the Intent JSON to the original message

{
  "event": {
    "version": "1.0",
    "session": {
      "new": false,
      "sessionId": "amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef",
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"
      },
      "attributes": {},
      "user": {
        "userId": "amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"
      }
    },
    "request": {
      "type": "IntentRequest",
      "requestId": "amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d",
      "timestamp": "2015-05-13T12:34:56Z",
      "intent": {
        "name": "airportinfo",
        "slots": {
          "AIRPORTCODE": {
            "value": "JFK",
            "name": "AIRPORTCODE"
          }
        }
      }
    }
  },
  "response": {
    "intent": {
      "name": "WEATHER_RESPONSE",
      "inputs": [
        {
          "name": "forecast",
          "value": "68 and sunny"
        }
      ]
    },
    "version": "1.0",
    "sessionAttributes": {},
    "response": {
      "shouldEndSession": true,
      "outputSpeech": {
        "type": "SSML",
        "ssml": "<speak>The weather at JFK is 68 and sunny.</speak>"
      }
    }
  }
}

Post the complete message to Dimension

https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and replace the API_KEY_HERE placeholder with your api key.

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"event":{"version":"1.0","session":{"new":false,"sessionId":"amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef","application":{"applicationId":"amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"},"attributes":{},"user":{"userId":"amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"}},"request":{"type":"IntentRequest","requestId":"amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d","timestamp":"2015-05-13T12:34:56Z","intent":{"name":"airportinfo","slots":{"AIRPORTCODE":{"value":"JFK","name":"AIRPORTCODE"}}}}},"response":{"intent":{"name":"WEATHER_RESPONSE","inputs":[{"name":"forecast","value":"68 and sunny"}]},"version":"1.0","sessionAttributes":{},"response":{"shouldEndSession":true,"outputSpeech":{"type":"SSML","ssml":"The weather at JFK is 68 and sunny."}}}}'
     'https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the API_KEY_HERE placeholder with your api key.

Example

View a complete example.