Dimension Labs API & Integrations

Amazon Alexa Advanced Integrations

The following lists some more advanced integration methods tailored to specific use cases.

Cloudwatch Logs

This integration path follows from creating an Alexa application via a separate service within AWS (such as AWS Lambda).

Requirements:

  • Alexa application is hosted separately from the Alexa Developer Console
  • aws-cli on host machine
  • permissions and connection to AWS Cloudwatch Logs from host machine
  • Dimension's library with peer dependency dimension-logger on the host machine

Configure Dimension Library

In your lambda function that handles Alexa Skills requests, call the logIntegration method
on the dimensino alexa object and pass configuration options as specified by the dashbot-logger library.
You are required to set the parameter logGroupName that you specify when creating your CloudFormation stack below.

const dimension = require("dimension")(
  "YOUR_DIMENSION_API_KEY"
).alexa.logIntegration({ logGroupName: "YOUR_LOG_GROUP_NAME" })



Once you create the stack, you will have your Alexa Skills Lambda function log to the Cloudwatch
Logs log-group. The log in your newly created log-group will then be passed to Dimension!

Alexa Specific Usage

Alexa Outgoing Intents (Optional)

Outbound Intents are an optional, advanced feature.

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

Here is how we define an intent:

  • intent – object – (optional)
    • name – string
    • inputs – array
      • input – object
        • name – string
        • value – string

Intents can be sent for either inbound or outbound messages. Place the intent object at the root level of the JSON that you send for each inbound or outbound message, or use the NPM module.

Adding an Intent for an outbound message

Example: “The weather is 68 degrees and sunny.”

Define Intent

The message “The weather is 68 degrees and sunny.” maps to the WEATHER_RESPONSE Intent with the “forecast” entity “68 and sunny”

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

Log outbound Intent via NPM

dimension.setOutgoingIntent({
  "name": "WEATHER_RESPONSE",
  "inputs": [
    {
      "name": "forecast",
      "value": "68 and sunny"
    }
  ]
});

Special NotHandled Intent

By passing the NotHandled intent, this will allow you to see which interactions were not handled by your skill

Log NotHandled Intent via NPM

dimension.setNotHandled();

Tracking Events in a Conversation

You may wish to track certain events in conversations, such as:

  • External URL Clicks
  • Social Shares
  • Revenue
  • Anything else…

JSON Format

The JSON that you can send to track an event is:

  • name – string (required)
  • userId – string (required)
  • conversationId – string (optional)
  • type – enum (required) - customEvent - revenueEvent - shareEvent - pageLaunchEvent

For each event type, you can pass additional properties:
customEvent

  • extraInfo – object (optional)

revenueEvent

  • amount – number (required)
  • referenceNumber – string (optional)
  • metadata – object (optional)

pageLaunchEvent

  • extraInfo – object (optional)

shareEvent

  • sharedMessage – object (optional)

referralEvent

  • name – string (required)
  • ref – string the referral tag (optional)
  • source – string the referral source (eg. ADS, WEB) (optional)
  • adid – _string an ID to identify the ad (optional)
  • refereruri – _string the URI that sent the referer(optional)

Tracking Custom Events

Post to the endpoint

https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=event&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:

{
  "name": "trackMeEvent",
  "type": "customEvent",
  "userId": "967295313370594",
  "extraInfo": {
    "start": 1500504070512,
    "difference": 374,
    "end": 1500504070886
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"trackMeEvent","type":"customEvent","userId":"967295313370594","extraInfo":{"start":1500504070512,"difference":374,"end":1500504070886}}'
     'https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

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

Tracking Revenue Events

Post to the endpoint

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

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

The data to POST should pass the following data:

{
  "name": "boughtSandwich",
  "type": "revenueEvent",
  "userId": "967295313370594",
  "amount": 17.45,
  "metadata": {
    "productName": "Ham Sandwich",
    "sku": "abc123123"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"boughtSandwich","type":"revenueEvent","userId":"967295313370594","amount":17.45,"metadata":{"productName":"Ham Sandwich","sku":"abc123123"}}'
     'https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

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

Tracking Page Launch Events

Post to the endpoint

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

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

The data to POST should pass the following data:

{
  "name": "Launched Detail Page",
  "type": "pageLaunchEvent",
  "userId": "967295313370594",
  "extraInfo": {
    "url": "https://www.dimensionlabs.io/"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"Launched Detail Page","type":"pageLaunchEvent","userId":"967295313370594","extraInfo":{"url":"https://www.dimensionlabs.io/"}}'
     'https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

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

Tracking Share Events

Post to the endpoint

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

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

The data to POST should pass the following data:

{
  "name": "sharedLink",
  "type": "shareEvent",
  "userId": "967295313370594",
  "sharedMessage": {
    "text": "come check out this bot"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"sharedLink","type":"shareEvent","userId":"967295313370594","sharedMessage":{"text":"come check out this bot"}}'
     'https://tracker.dimensionlabs.io/track?platform=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

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

Tracking Custom User Metadata

You can send any custom user metadata to build detailed audience segments.

Custom user metadata can be sent for both incoming and outgoing messages.

Examples of metadata that you might send:

  • Your own User ID
  • Experiment Group, for A/B Testing
  • Favorite Book
  • Location

To send Custom User MetaData

To pass custom metadata, set the dimensionUser session attribute

'NewIntent': function () {
 //generate a new fact using an array of available facts (data)
  ...
 this.attributes.dimensionUser = {
  favoriteBook: 'Harry Potter'
 }
 ...
 this.emit(':responseReady');
}

Or, in the outgoing JSON:

 "dimensionlabs_timestamp": 1529391516389,
 "event": {
  ...
 },
 "response": {
  "version": "1.0",
  "response": {
   "shouldEndSession": false,
   "outputSpeech": {
    "type": "SSML",
    "ssml": "<speak> <audio src="https://s3.amazonaws.com/volley-voice-service-prod/output_1ca64570533a435a28316bafaa766fdc.mp3" /> </speak>"
   },
   "reprompt": {
    "outputSpeech": {
     "type": "SSML",
     "ssml": "<speak> <audio src="https://s3.amazonaws.com/volley-voice-service-prod/reprompt_1ca64570533a435a28316bafaa766fdc.mp3" /> </speak>"
    }
   }
  },
  "sessionAttributes": {
   "dimensionUser": {
    "favoriteBook": "Harry Potter"
   },
   ...
  }
 }
}

Alexa User Exclusion

In certain cases, you may want to exclude certain user IDs (test users, internal users) from your analytics at Dimension. For other platforms, you may simply exclude these users yourself, based on the User ID, but if you are using our Alexa integration, that is not possible.

So, we have added a configurable method to exclude a list of user IDs.

To pass this list, modify the Dimension call to pass the list of user IDs to ignore.

const ignoreUserIds = [
  'userID-123123123',
  'userID-234234234'
];
const dimension = require('dimension')(
  process.env.DIMENSION_API_KEY,
  { ignoreUserIds }
).alexa;

Device Capabilities Report

Dimension has a powerful Device Capabilities Report that will tell you how many of your users are accessing your skill with a display capable device.

In order to see data for this, however, you must enable the Display Interface for your skill prior to submission to Amazon.

In order to do this, go to your Alexa Developer Console, and under the “Interfaces” menu, turn on the “Display Interface” selection

Once this is enabled, you will see a Device Capability report that looks like this: