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.
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.
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.
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
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.
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:
These are the most basic events. Your Skill gets a notification when someone enables or disables your Skill in the Alexa companion app.
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.
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.
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.
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.
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.
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:
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:
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.
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
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.