Amazon Alexa

Integration published by Jovo | 42,160 downloads

Build apps for Amazon's Alexa assistant platform

Echo Button and Gadget Skills

GadgetController Interface

With the GadgetController interface you can create animations for the light bulb in the Echo Button.

But first you have to enable the GadgetController interface either in your project.js file, if you're working with the Jovo CLI, or in the Alexa Developer Console in the Interfaces tab.

To do it with the Jovo CLI simply add the interface to the alexaSkill object in your project.js:

Don't forget to build and deploy your project after you've added the interface:

Set Light

To change the light of the user's Echo Buttons you have to use the GadgetController.SetLight directive

The directive has the following parameters you have to set: Name Description Value Required
targetGadgets Specify the gadget IDs to which the animation should be applied. If you don't specify the target gadgets, every single one will receive the animation String[] with gadget IDs no
triggerEventTimeMs The amount of time to wait after the trigger event before playing the animation Number min: 0, max: 65535 yes
triggerEvent Specify the action that triggers the animation. Either buttonDown (button pressed), buttonUp (button released) or none (trigger animation as soon as the directive arrives) String yes
animations Array of animations you want to use Object[] yes

Animations

The animations object contains the animation steps in chronological order as well as the number of repetitions.

Name Description Method Value Required
repeat The number of times to play the animation repeat(repeat) Number min: 0, max: 255 yes
targetLights Array of Strings representing the lights on the device. Since the Echo Button only has one you have to use ['1'] targetLights(targetLights) String[] yes
sequence Array of objects, which define the animation. The array has to be in chronological order sequence(sequence) Object[] yes
Sequence

A sequence is simply an array of steps, which can each have a different color, duration, etc.. Every sequence can only have a set amount of steps, which depends on the number of gadgets that sequence has to be applied to. Amazon provides a formula to calculate the number of steps allowed: maxStepsPerSequence = 38 - numberOfTargetGadgetsSpecified * 3.

You can also have a zero-step animation that will clear the current animation set for the trigger.

A sequence has the following parameter:

Name Description Method Value Required
durationMs The duration of the step in milliseconds duration(duration) Number in milliseconds yes
color The desired color color(color) String in RGB hexadecimal notation yes
blend Choose if you want the previous color to smoothly change to this step's one blend(blend) boolean yes

Game Engine Interface

The Alexa GameEngine interface provides the toolset to receive Echo Button events using the Input Handler.

To get a better understanding how the GameEngine interface works you should go for a bottom up approach since everything is built in top of each other. Therefore we will start with the Recognizers first proceed with the Events, go over the Start- and StopInputHandler directive and finish with the InputHandlerEvents.

But first you have to enable the GameEngine interface either in your project.js file, if you're working with the Jovo CLI, or on the Alexa Developer Console in the Interfaces tab.

To do it with the Jovo CLI simply add the interface to the alexaSkill object in your project.js:

Don't forget to build and deploy your project after you've added the interface:

Recognizers

The primary use case of recognizers is to track Echo Button inputs to look for patterns, which were defined at the creation of the respective recognizer. These are called PatternRecognizer.

There are also two varations, which can either track the progress of another recognizer or check if the user has deviated from an expected pattern, called ProgressRecognizer and DeviationRecognizer respectively.

Recognizers are either true or false at any point of time. Examples:

  • The user has not reached the defined progress of your ProgressRecognizer, which means the recognizer is currently false.
  • The user has deviated from the pattern you specified in the DeviationRecognizer, which means the recognizer is currently true.

Pattern Recognizer

As described earlier, the PatternRecognizer tracks the raw Echo Button events to look for the specified pattern.

Name Description Method Value Required
anchor Define where the pattern has to appear in raw Echo Button event history. Either at the start (first event in the pattern must be the first event in the history), at the end (last event in the pattern must be last event in the history) or anywhere (the pattern can appear anywhere in the history) patternAnchor(anchor) String no
fuzzy Decide how strict the pattern match is. While true it will recognize the pattern even if there are extra events in between. Here's an example from Amazon: "Consider a pattern that requires three down events while the button is colored red. If the player presses the button four times with the pattern "red, red, green, red," then fuzzy matching would accept the overall match, while non-fuzzy matching would reject the match." fuzzy(fuzzy) boolean no
gadgetIds Specify which gadgets should be tracked for the pattern using their respective gadgetIds gadgetIds(gadgetIds) String[] no
actions Specify the actions to consider for this pattern. down (button is pressed), up (button is released), silence (no action) actions(actions) String[] no
pattern An array of pattern objects ordered chronologically. pattern(pattern) Object[] yes

Pattern Object

A pattern object has three values, namely gadgetIds, colors and action. None of the values are required, but if they are left out, they will be handled as wildcards, i.e. everything works.

Name Description Value
gadgetIds Specify which gadgets should be eligible for this match String[]
colors Specify the colors that should be eligible for this match String[] - RGB hexadecimal notation
action Specify the action that must match. Either down, up or silence (the same as above). String
Code Example for Pattern Recognizer

To create a PatternRecognizer you need the PatternRecognizerBuilder:

With the builder you can use the methods described above:

Deviation Recognizer

The deviation recognizer is used to check if the player has deviated from an expected pattern defined in one of your pattern recognizers.

Name Description Method Value Required
recognizer Name of the recognizer where the pattern was defined recognizer(nameOfPatternRecognizer) String yes
Code Example for Deviation Recognizer

To create a DeviationRecognizer you need the DeviationRecognizerBuilder:

With the builder you can use the method described above:

Progress Recognizer

The progress recognizer is used to monitor how close the user is to completing the pattern of one of your pattern recognizers.

Name Description Method Value Required
recognizer Name of the recognizer where the pattern was defined recognizer(nameOfPatternRecognizer) String yes
completion The point from which on the recognizer is true completion(completion) Number (e.g 50 = 50%) yes
Code Example for Progress Recognizer

To create a ProgressRecognizer you need the ProgressRecognizerBuilder:

With the builder you can use the methods described above:

Events

Events are used to define the conditions under which your skill will be notified of Echo Button input. You define these conditions using the recognizers we discussed above.

Name Description Method Value Required
meets When all the recognizers you specified here are true, your skill will be notified meets(meets) String[] yes
fails If any of recognizers specified here are true, your skill won't receive a notification fails(fails) String[] no
reports Specify which raw button events should be sent with the notification. Either history (all button events since the Input Handler was started), matches (all button events that contributed to this event) or nothing (no button events. Default) reports(report) String no
shouldEndInputHandler Specify if the Input Handler should end after receiving the event shouldEndInputHandler(shouldEnd) boolean yes
maximumInvocations Number of times the event can be sent to your skill maximumInvocation(maxInvocations) Number min & default: 1, max: 2048 no
triggerTimeMilliseconds Specify how many milliseconds have to have passed before the event can be sent out triggerTimeMilliseconds(triggerTime) Number min: 0, max: 300000 no

Code Example for Events

To create an Event you need the EventBuilder:

With the builder you can use the methods described above:

StartInputHandler

The StartInputHandler directive is the starting point at which you define the conditions under which your skill will receive the Echo Button events. At any point of time there can only be a single Input Handler active.

The directive has the following four parameters, which are all required besides proxies:

Name Description Value
timeout Maximum run time of the Input Handler in milliseconds Number min: 0, max: 90000
proxies Temporary identifiers to assign to gadgets which your skill hasn’t yet discovered. You can use these proxies at places where you would normally use actual gadget IDs String[]
recognizers Recognizers track Echo Button inputs to look for patterns, which were defined at the creation of the respective recognizer Object min: 0, max: 20
events Events use recognizers to determine whether your skill should be notified or not Object min: 1, max: 32

StopInputHandler

You can at any point in time stop receiving Echo Button events using by stopping the Input Handler:

Input Handler Events

After you started the Input Handler your skill will be able to receive InputHandlerEvents. These are the events you specified beforehand and are received just like any other request.

Jovo maps these requests to the built-in ON_GAME_ENGINE_INPUT_HANDLER_EVENT intent, where you can access the events sent with the request:

Responding to Input Handler Events

Responding to GameEngine requests is optional. If you do respond Alexa handles the respond the usual way with slight differences:

  • Card will only be displayed on Echo devices with a screen, not the app.
  • Responses to GameEngine requests can't end the skill session, which means the shouldEndSession parameter in your response will be ignored
  • An error in your response won't end the session but rather trigger a System.ExceptionEncountered error request.

Amazon Alexa Changelog

Jovo Marketplace | GitHub | npm

Current version might be higher than the latest changes displayed below because of updates of dependencies.

2020-08-21 [3.0.30]

3.0.17 (2020-05-13)

🐛 Bug fix

  • jovo-platform-alexa Fix http status in ReminderAPI

Committers: 1

3.0.13 (2020-05-04)

💅 Enhancements

  • jovo-platform-alexa #734 Add getPermissionIsCardThrown (@rmtuckerphx)
  • jovo-platform-alexa Add types for skill event body objects

Committers: 2

3.0.11 (2020-04-06)

  • Updated Typescript to 3.8.x
  • Updated Prettier to 2.x

Committers: 2

2.x

Find the 2.x changelog here.

Join Our Newsletter

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