If you are already familiar with the Adobe Analytics APIs then creating an Adobe Analytics-Amazon Alexa Skill is a pretty simple process.
Building Alexa Skills with the Alexa Skills Kit
STEP 1: Create a New Skill
If you haven’t already, your first step is to create an Amazon Developer account. Once you have an account, then you can create your first skill.
From the Alexa Skills area, click ‘Add a New Skill’
STEP 2: Skill Information
- Name: This is the name of your Skill should you choose to deploy it to the Alexa App Store.
- Invocation Name: This is the name a user will use to call your Skill e.g. Alexa ask Adobe….
- Application Id: This is a unique identifier for your application and is use as a check, within your endpoint script (more on that later), to ensure that the service calling your script is your Alexa Skill and no one else.
STEP 3: Interaction Model
The Interaction Model defines how users will interact with your skill.
Intent Schema
The Intent Schema is a JSON Object that defines the key words and phrases that are spoken by a user and how it maps to your Skill. For this example, we are building a very basic skill that simply accepts a reporting time period as an input. We accomplish this by defining an intent, GetDate, and a Slot that will hold the key reporting time period values. The Slot is defined using a name, ReportDate, and in this instance a list of valid dates for the Skill defined as LIST_OF_DATES.
Custom Slot Types
In this example, we are using a custom type we defined as LIST_OF_DATES and then we provided a pipe delimited list of valid values for this slot type e.g. today | yesterday | this week | last week
Sample Utterances
Finally, we will provide a few samples that users will use to invoke our Skill.
STEP 4: Configuration
The configuration step is where you define your Skill Endpoint, or where the script that will handle the backend processing (in our case connecting to Adobe Analytics via an API call and returning a response to the Alexa Skill) is located. You can either host your script on Amazon AWS or you can host your script on any HTTPS enabled server. For this example, we choose to host the Endpoint, as a PHP script, on our server.
STEP 5: SSL Cert
If you choose to host the Endpoint on your own server, it must be enabled with an SSL Cert. Choose the appropriate option for your environment.
STEP 6: Test
As part of the Skill setup, Amazon provides a very handy simulator that allows you to test the inputs and outputs of your Skill. You can add the text that a user would speak to Alexa to trigger your skill, or there is even a voice simulator if you want to actually test the voice translation.
On the left, you see the JSON that is sent to your Skill Endpoint. For this simple example, we are mostly interested in grabbing the value from the ReportDate Slot so we know what reporting timeframe to use for our Adobe Analytics API call.
On the right, you see the JSON that our Skill Endpoint compiled and returned to the Amazon server. You can see that here we are defining the actual text that Alexa will speak as a reaction to invoking our Skill.
That’s it! This gives you all the basic info you need to setup your first skill. Now let’s take quick look at our Skill Endpoint.
Building an Alexa Skill Endpoint
STEP 1: Handle the Skill Request from Alexa
As we saw using the simulator, Alexa will send your Endpoint a JSON object with all of the key data points you need to act on.
//Grab the JSON sent from Amazon Alexa Skill
$data = file_get_contents('php://input');
//Decode JSON
$json=json_decode($data);
//Grab the reporing timeframe from the slot definition
$date = $json->request->intent->slots->ReportDate->value;
//A function to translate the reporting timeframe from Alexa into the proper date format e.g. today -> 2017.03.21
$rptDates = getReportDate($date);
STEP 2: Query Adobe
Our example will return a pre-defined metric, in this case visits, but in theory your Skill could be configured to send your end point any combination of Metrics, Dimensions, and Timeframes you could use to build your Adobe API query. There are countless examples of using the Adobe APIs to query your Analytics data out there, in many different languages, so I will not go into detail on how to make those calls here.
//Query the Adobe Reporting API to return the metric 'Visits' based on a start and end date as defined by the Alexa request $results = getReportData($startDate,$endDate);
STEP 3: Send Response to Amazon
The final step is to parse the data returned by the Adobe API and compile a JSON response that will inform Alexa how to speak the results.
//Grab the number of Visits from the Adobe API reponse
$instances = $results->report->totals[0];
//Format the text string you want Alexa to speak
$text= "Your website had " . $instances . " visits " . $date;
//Package up your JSON response and send to Amazon
$response = new \Alexa\Response\Response;
$response->respond($text);
$response->endSession();
header('Content-Type: application/json');
echo json_encode($response->render());
exit;
NOTE: If you are logged into your Alexa device with the same developer account credentials used to build your Skill, you can now invoke your Skill using your Alexa device as shown in the video above.
RESOURCES
Getting Started with the Alexa Skill Kit
Alexa Developer Formum
Adobe I/O
Adobe API Documentation