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:

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.

Copied to clipboard.

    "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

  1. Go to developer.amazon.com/alexa.
  2. Click Your Alexa Consoles, and then click Skills. The developer console opens and displays any skills you have already created.
  3. Locate the skill you want to configure, and then click Edit.
  4. Navigate to the Build > Interfaces page.
  5. Enable the Alexa Web API for Games interface.
    When you select this option, you add the ALEXA_PRESENTATION_HTML to the skill manifest.
  6. 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.

Copied to clipboard.

    "device": {
      "deviceId": "amzn1.ask.device.XXXX",
      "supportedInterfaces": {
        "Alexa.Presentation.HTML": {
          "runtime": {
            "maxVersion": "1.1"
          }
        }
      }
    }

Copied to clipboard.

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.

Copied to clipboard.

  "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 is false, Alexa speaks the provided outputSpeech, and then opens the microphone for a few seconds to get the user's response.
  • When shouldEndSession is 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.

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.

Copied to clipboard.

{
    "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.

Copied to clipboard.

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 to true.
  • 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:

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:

Was this page helpful?

Last updated: May 01, 2024