Understand the Alexa Web API for Games
Build with the Alexa Web API for Games
To create a game with the Alexa Web API for Games, you build two parts:
- An Alexa custom skill that starts up the web app and handles voice requests. Your skill code uses the Alexa.Presentation.HTML interface to start the web app, and then communicate with the app while it runs.
As you plan and build your skill, you can build these pieces independently, and then add the integration later. For example, you can create a fully functional web app for your game, and then add in the calls for Alexa speech and voice control later.
How users interact with the skill and web app
Users invoke and interact with your skill normally. Your skill starts the web app part of the experience at an appropriate point in the interaction, such as in the response to an
IntentRequest. For example, you might design your skill to ask the user if they're ready to start:
User: Alexa, open My Web Game
Alexa: Welcome to My Web Game. Are you ready to begin?
Alexa: OK, starting the engines… (sound effects)
Skill launches the web app and displays the starting page.
After the web app starts, the user can interact with the app by using both tap and voice, or remote and voice. For example, the user can:
- Press buttons on the screen. These actions might trigger Alexa speech or other actions within your web app.
- Speak commands to the game (for example, "Alexa, fire the missiles!")
- Respond to voice prompts triggered by your app (for example, "That was a miss! Do you want to try again?").
This interaction continues until the web app closes. For example, when the user says, "Alexa, exit.".
Communication between your skill and your web app
While the user interacts with your web app, you use the
Alexa.Presentation.HTMLinterface provides your skill with directives and requests for communicating with the web app. Your skill returns directives to send information to the web app, and uses request handlers that can listen for events coming from the web app.
Alexaclass with methods and properties for communicating with the skill. Your web app calls methods on this class to send messages to the skill, and registers callbacks to listen for events coming from the skill.
The following list shows the communication flow:
- The user invokes your skill and then triggers the request to start the web app. Your skill gets a normal
- The request handler in your skill code returns a response with the
Alexa.Presentation.HTML.Startdirective. This directive tells Alexa to start the web app.
- The device launches your web app.
- The user begins interacting with the web app normally.
When the game is running, communication flows between the skill and the app:
- The web app calls
alexa.skill.sendMessage()to send messages to the skill, such as an event that says that Alexa should prompt the user for voice input. Each message can include data you define to represent what's happening in the web app. You can also provide an optional callback to get a status code that shows whether the
sendMessage()call was successful.
- The web app sends these messages to the skill in the
Alexa.Presentation.HTML.Messagerequest. The skill handles these incoming requests, and then responds with directives and output speech.
- The skill returns the
Alexa.Presentation.HTML.HandleMessagedirective to send messages to the app.
- The web app registers a callback to respond to incoming messages sent from the skill (
alexa.skill.onMessage()). The app can only register one callback, so the callback function should include logic to handle different messages based on the data provided within the message.
alexa.skill.sendMessage()to catch throttling errors caused when your app exceeds this limit. The
MessageSendResponseindicates the error to your callback.
For examples about how you use communication between the skill and web app to build in voice control and Alexa speech responses, see Add Voice Control and Speech to the Web App.
The web app and skill session
The web app changes the normal skill session lifecycle. For details, see the following sections:
Start the web app and keep the session open
When your skill sends the directive to start the web app, the response must include
shouldEndSession set to either
false or undefined (not set). This setting keeps the skill session open so that the user can interact with the web app on the screen.
false, Alexa speaks the provided
outputSpeech, and then opens the microphone for a few seconds to get the user's response.
shouldEndSessionis undefined, Alexa speaks any provided
outputSpeech, but doesn't open the microphone. The session remains open.
The session remains open as long as the web app is active on the screen. This behavior is different from a normal skill with screen content, such as a skill built with Alexa Presentation Language or the display templates. For those skills, the session can remain open for approximately 30 seconds.
What closes the web app?
When the device displays your web app, your app remains active on the screen. The following actions close the app:
- The skill session ends.
- The skill returns a directive from an interface other than
Alexa.Presentation.HTML. This action closes the web app, but doesn't necessarily close the skill session.
For example, when the skill returns an Alexa.Presentation.APL.RenderDocument, the device closes the web app, and then inflates the provided document. The skill session then has the lifecycle described in How devices with screens affect the skill session until the skill sends another
Alexa.Presentation.HTML.Start directive to restart the web app.
What ends the skill session?
Any of the following actions can end the session:
- Your skill returns a response with
- The user ends the skill with "Alexa, exit.".
- The user exits the skill with "Alexa, go home.".
- The user stops interacting with the web app, and then leaves it idle. After the duration of the configurable timeout (up to 30 minutes), the skill session ends. Specific devices might choose to ignore the configured timeout value, or set a lower bound.
When the skill session ends, the web app closes.
Can I use both Alexa Web API for Games and APL in the same skill?
You can use both the Alexa Web API for Games and APL in your game. However, you can't mix the two in a single screen. For a given response, you can display either the web app or an APL document.
When your web app is already displayed on the screen, sending the
ExecuteCommands directive closes the app. Make sure to save any state information as needed for your game.
To use APL in your skill, make sure to configure your skill to support the APL interface (
ALEXA_PRESENTATION_APL in the skill manifest).
Requirements for the skill and web app
To use the Alexa Web API for Games, your skill and your web app must meet the following requirements.
- Configure your skill to support the Alexa Presentation HTML Interface.
- Host your web app at an internet-accessible
HTTPSendpoint. The web server must present a valid and trusted SSL certificate.
- The web app must be a game. Other types of apps can't use the Alexa Web API for Games.
Test your skill and the web app
You can use Chrome DevTools on your development computer to debug your skill's web app that's running on an Amazon Fire TV device. For details, see Using Web App Tester and DevTools.
Use of HTML game engines and relevant libraries
With Web API for Games, you can use various techniques and tools to manage graphics and advanced audio. You can do animation with HTML and CSS, Canvas, SVG, and WebGL. Developers have numerous HTML game frameworks and libraries to choose from. The following list shows some popular options:
- Phaser – game framework for Canvas and WebGL
- Pixi.js – game framework and 2D graphics using WebGL
- three.js – 3D library and app framework using WebGL
- Howler.js – audio library