[Tutorial] How to use Alexa Skill Events with the Jovo Framework

By Kaan Kilic (@KnKlc8), published on April 24th, 2018, last modified on June 1st, 2018 at 3:59 pm
Tags: Amazon Alexa, Tutorials, Voice App Development

Learn more about the implementation of Alexa Skill Events in your Jovo project to get notified when your users interact with your Skill outside the active usage, for example when they enable your Skill or do account linking.

ūüďč You can find the full code example of this tutorial here: jovo-templates/alexa/skillevents.

Contents

Jovo is an open-source development framework for building voice apps that work on both Amazon Alexa and Google Assistant with only one code base. Take a look at the Jovo Framework Docs or our Voice App Courses to learn more.

 

Introduction to Alexa Skill Events

For a long time, it has been difficult to track and understand how users engage with an Alexa Skill. When did they enable the Skill? Did they just stop using it or did they even take the action to disable it from the Skill store? Finally, there is a way to track some of the ways how users interact with your Alexa Skill: Events.

Alexa Skill Events can be used to notify you if a certain event occurs, which range from the customer disabling your Skill to them linking their account using the Alexa app. The notification comes in form of a request to your Skill, which you can then access and act on.

How to enable Skill Events

The tricky part about Alexa Skill Events is that they can’t be enabled through the Amazon Developer Portal. To enable them, you need to use ASK CLI (the command line interface of the Alexa Skills Kit), or use the Alexa Skill Management API (SMAPI)¬†directly.¬† An events object needs to be added to the skill.json file, which looks like this:

This specifies the endpoint that is called from the Skill events, and subscribes to a number of events that are specified in the subscriptions array.

To enable the Skill Events, the modifications to the skill.json need to be pushed to the Amazon Developer Portal by using the ASK CLI. Find out more how it works in the implementation section below.

Supported Events

The Alexa Skill Events currently support five interactions, which you can add to your Skill individually. Every single one of these requests contains basic data like user ID and timestamp, which allows you to map every request to an individual user.

The following events are supported:

Skill Enabled/Disabled

These are the most basic events. Your Skill gets a notification when someone enables or disables your Skill in the Alexa companion app.

Account Linked

This event is triggered after your user has linked their account with your service using the Alexa companion app. The incoming request after the event is triggered will contain the same access token, which you also get with every request after your user linked their account. Learn more about Alexa Account Linking here: Login with Amazon, Account Linking with Auth0.

Skill Permission Accepted

If your user grants permissions (e.g. access to your user’s lists or their location) for the first time or if they grant them after they were revoked, this Skill Event¬†is triggered. The request includes the most recently accepted permissions. Check out the sample requests in the official documentation to get a feeling for the JSON structure.

Skill Permission Changed

This Skill Event is triggered when your user grants your Skill additional permission or revokes existing ones. The request includes the most recently accepted permissions.

 

Implementation with Jovo

Now that we know how the Alexa Skill Events are structured. let’s learn how to access the requests in Jovo. To subscribe to events, you have two options:

After this, you can set up the code to Receive the Event Requests in your Jovo app.

Alternative 1: Modify the Skill.json

If you have already created the platform specific language model files with jovo build, you can find the skill.json in the /platforms/alexaSkill/ folder of your Jovo project. Learn more about the platforms folder here.

The skill.json of a newly created project looks like this:

To use the Skill Events you have to add the events object, which contains an endpoint (in most cases your Jovo Webhook or¬† Lambda function) and the events, which you want to enable. Here’s an example:

Don’t forget to add your own endpoint to the skill.json¬†if you copy and paste the example.

After that deploy your changed skill.json using the Jovo CLI:

 

Alternative 2: Use the Template

There is an even easier way than the one above! If you don’t want to manually change¬†the¬†skill.json¬†file, you can also just download the Jovo Template for Alexa Skill Events:

This comes with a modified app.json (usually created with jovo init), which looks like this:

As you can see, the section is added to the manifest object and is added to the skill.json during the jovo build command.

To get it to work, add your endpoint to both the events object and the endpoint below, and use the following commands:

That’s it!

The template also comes with a handler that makes it easier for you to access the Alexa Skill Event requests, which you can find in the next section.

Receive the Event Requests with Jovo

As I said earlier, the incoming requests are mapped to handlers of the Jovo framework. The only thing you have to do is to add them to your handlers in your app.js file (which is already done if you use the Skill Events template). These handlers are placed into the ON_EVENT directive state to keep things organized:

Currently this implementation will only log that these events occured, which is not that useful, but I am sure you will find great use cases for the Alexa Skill Events.

You can access the bodies of the event requests with this.alexaSkill().getSkillEventBody().

That’s it, you made it to the end!

 

Any questions? Please let us know in the comments below ūüĎá.
You can also reach us on Twitter or Slack.

Join Our Newsletter

Be the first to get our free tutorials, courses, and other resources for voice app developers.