Build Your Alexa Skill for Web App Games
You can build a voice-enabled gaming skill by using the custom voice interaction model. Design your game to include all or part of the game logic in the skill. Use HTML directives to start the web app and send instructions and data throughout the game. Use regular Alexa directives to communicate with the Alexa service. For more details about the Alexa Web API for Games, see About Alexa Web API for Games.
Prerequisites
To build an Alexa skill for web app games, you must meet the following prerequisites:
- You need an Amazon developer account.
- Create a skill that uses the custom voice interaction model. For more details about custom skills, see Understand Custom Skills.
Configure your skill to support HTML directives
To enable the HTML directives in your skill, you must add the ALEXA_PRESENTATION_HTML
interface in your skill manifest by using the ASK Command Line Interface (CLI) or the developer console. For more details about the skill manifest, see Skill Manifest Schema.
Add the interface by using the CLI
To configure your skill to support HTML directives, add the ALEXA_PRESENTATION_HTML
interface to the manifest.apis.custom.interfaces
in the skill manifest JSON file.
The following example shows skill manifest configured with the HTML interface.
"apis": {
"custom": {
"interfaces": [
{
"type": "ALEXA_PRESENTATION_HTML"
}
]
}
}
After you save your manifest file, use the Alexa Skills Kit Command Line Interface to deploy the changed manifest.
Add the interface in the developer console
You can also configure the skill manifest in the developer console.
To add support for the HTML interface
- Go to developer.amazon.com/alexa.
- Click Your Alexa Consoles, and then click Skills. The developer console opens and displays any skills you have already created.
- Locate the skill you want to configure, and then click Edit.
- Navigate to the Build > Interfaces page.
- Enable the Alexa Web API for Games interface.
When you select this option, you add theALEXA_PRESENTATION_HTML
to the skill manifest. - Click Save Interfaces, and then, to rebuild your interaction model, click Build Model.
Verify that the device supports HTML directives
Not all devices support the Alexa.Presentation.HTML
directives. Before your skill launches the web app, determine whether the device supports HTML directives by inspecting the LaunchRequest
, IntentRequest
, or In Skills Purchase Connections.Response
for Alexa.Presentation.HTML
. If the device supports HTML, respond with the Start
directive to load your web app.
The following example shows the context.System.device.supportedInterfaces
object with HTML support.
"device": {
"deviceId": "amzn1.ask.device.XXXX",
"supportedInterfaces": {
"Alexa.Presentation.HTML": {
"runtime": {
"maxVersion": "1.1"
}
}
}
}
const supportedInterfaces = Alexa.getSupportedInterfaces(handlerInput.requestEnvelope);
const htmlInterface = supportedInterfaces['Alexa.Presentation.HTML'];
if(htmlInterface !== null && htmlInterface !== undefined) {
// Add a start directive.
}
Support for the HTML interface is separate from support for Alexa Presentation Language (APL). A device might support APL, but not support HTML. Therefore, check for the HTML support separately.
Start the web app
To notify the Alexa Service that you want to start a web app, use the Alexa.Presentation.HTML.Start
directive in the Response
object. Include the HTTPS link of the webpage to load onto the device. The SSL certificate must be valid for the webpage to open on an Alexa-enabled device.
For more details, see Alexa.Presentation.HTML.Start
.
The following example shows a Start directive.
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "Plain text string to speak",
"playBehavior": "REPLACE_ENQUEUED"
},
"directives": [
{
"type": "Alexa.Presentation.HTML.Start",
"data": {
"arbitraryDataKey1": "Initial start up information"
},
"request": {
"uri": "https://mydomain.example.com/mygame.html",
"method": "GET"
},
"configuration": {
"timeoutInSeconds": 300
}
}
],
"shouldEndSession": false
}
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:
- When
shouldEndSession
isfalse
, Alexa speaks the providedoutputSpeech
, and then opens the microphone for a few seconds to get the user's response. - When
shouldEndSession
is undefined, Alexa speaks any providedoutputSpeech
, 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.
Communicate with the web app
Your Alexa skill can send messages to your web app running on the device, letting the skill hold all or part of the game logic. Your skill might send a message to the app when the skill receives an IntentRequest
or in response to a message from your web app. When your skill receives a message from the web app, you can respond with directives and output speech Alexa should say.
Use the Alexa.Presentation.HTML.HandleMessage
directive to communicate with the app. The directive gives you the flexibility to define your own interface to your web app by formatting the message
as needed. For more details, see Alexa.Presentation.HTML.HandleMessage
.
The following example shows how to send arbitrary state data from your skill.
{
"type": "Alexa.Presentation.HTML.HandleMessage",
"message": {
"players": 1,
"myGameState": "Level 2",
"speech": "Are you ready for the next level?"
}
}
Your skill can handle an incoming Alexa.Presentation.HTML.Message
event just like you would handle an IntentRequest
. For more details, see Alexa.Presentation.HTML.Message
.
The following example shows a message handler.
const myWebAppLogger = {
canHandle(handlerInput) {
return Alexa.getRequestType(handlerInput.requestEnvelope) === "Alexa.Presentation.HTML.Message";
},
handle(handlerInput) {
const messageToLog = handlerInput.requestEnvelope.request.message;
console.log(messageToLog);
return handlerInput.responseBuilder.getResponse();
}
}
Close the web app
When the device displays your web app, your app remains active on the screen. The following actions close the app:
- Your 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. - Your skill returns a response with
shouldEndSession
set totrue
. - 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
timeoutInSeconds
(up to 30 minutes), the skill session ends. Specific devices might choose to ignore the configured timeout value, or set a lower bound.
For example, when your skill returns an Alexa.Presentation.APL.RenderDocument directive, 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.
About using 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 the device screen displays your web app, sending the Alexa.Presentation.APL.RenderDocument
directive or ExecuteCommands
directive closes the app. Make sure to save any state information as needed for your game.
APL and the Web API for Games use different interfaces within the Alexa.Presentation
namespace. To use both, configure your skill to support both Alexa.Presentation.APL
and Alexa.Presentation.HTML
:
- Configure your skill to support HTML directives
- Configure your skill to support the Alexa.Presentation.APL interface
A given device might not necessarily support both of these interfaces. Make sure the device supports the interface you're using before sending the relevant directives:
Related topics
- Build Skills in the Alexa Developer Console
- Skill Manifest REST API Reference / Get skill manifest
- Skill Manifest REST API Reference / Update skill manifest
- Service Interface Reference
- Web API Extensions for Games Overview
Last updated: May 01, 2024