Build Your Web App with Web API for Games

You can use the Alexa Web API for Games to build voice-enabled games with JavaScript, HTML5, CSS, and Web Audio. You can use well-known techniques and tools to manage graphics and audio. Add animation with HTML and CSS, Canvas, SVG, and WebGL. Developers have a number of JavaScript game frameworks and libraries from which to choose. The following list shows some popular options:

  • Phaser – game framework for Canvas and WebGL
  • Pixi.js – game framework and 2D graphics that uses WebGL
  • three.js – 3D library and app framework that uses WebGL
  • Howler.js – audio library

Build with the Alexa Web API for Games

To create a game with the Alexa Web API for Games, your web app must be able to display in a browser and interact with users.

Host your web app and associated assets at an internet-accessible HTTPS endpoint. The web server must present a valid and trusted SSL certificate to the Alexa device. To decrease latency and enhance the gaming experience, use a storage solution and a content delivery network with edge locations around the world. For example, Amazon S3, Amazon CloudFront, or any web server that hosts HTTPS.

You can design your game to include game logic in either the web app or in the skill backend. To communicate with the skill, use the Alexa HTML API in your app .

Add the Alexa JavaScript library to your app

To load the Alexa HTML JavaScript library, include the URL in a script tag on your HTML page, as shown in the following example.

Copied to clipboard.

<head>
      <script src="https://cdn.html.games.alexa.a2z.com/alexa-html/latest/alexa-html.js"></script>
</head>

Create the Alexa client

Your app communicates with the device and with your skill with the Alexa Client object. To prevent the client from being available before it's ready to serve requests, create the Alexa Client object with a static factory function. Invoke the function one time on each page. For more details, see Client object.

The following example shows Alexa Client object initialization.

Copied to clipboard.

var alexaClient;
Alexa.create({version: '1.1'})
     .then((args) => {
         const {
             alexa,
             message
         } = args;
        alexaClient = alexa;
        document.getElementById('debugElement').innerHTML = 'Alexa is ready :)';
     })
     .catch(error => {
        document.getElementById('debugElement').innerHTML = 'Alexa not ready :(';
     });

Communication between your skill and your web app

When the user interacts with your web app, you can send messages between your web app running on the device and the skill back end. This communication allows the Alexa skill to hold some game logic, send local inputs, receive voice inputs, and incorporate in-skill purchases. Use the Alexa.Presentation.HTML.Message directive and the Alexa.Presentation.HTML.HandleMessage event in your skill to communicate with the web app.

In your web app, use the Alexa client and the sendMessage and onMessage JavaScript APIs to communicate with your skill. The Alexa HTML API lets your web app register additional handlers to listen for other events, such as when Alexa begins and ends speech. You can use these handlers to build the flow between on-screen events, for example, button presses and voice commands. For more details, see Add Voice Control and Speech to the Web App.

End the web app session

When the device displays your game, your app remains active on the screen until one of the following actions occurs:

  • The user ends the skill session or the game.
  • The skill ends the session.
  • The skill uses an interface other than Alexa.Presentation.HTML.

Test your skill and the web app

You can use Chrome DevTools on your development computer to debug your web app that's running on an Amazon Fire TV device. For more details, see Using Web App Tester and DevTools.

Best practices

General best practices for building websites apply to the web app used with your Alexa skill.

  • Use a storage solution and a content delivery network to store and cache your assets across servers worldwide, close to where your players are. Keeping your web server at edge locations greatly reduces potential latency associated with your players' experience.
  • The device displays an initial flash of white when the WebView browser starts. You can't control the flash.
  • Set a background color or page style while your assets load to let the user know that your game is getting ready to use.
  • To avoid a "flashing" effect, keep the background color consistent during loading and when your app is ready for use.
  • The device caches assets according to the cache-control header. Make sure to account for the cache in development and use it in production.
  • Players might prefer to use their voice for some interactions and tap for others. Consider adding optional corresponding tap interactions for some core game controls. You have full control over most Document Object Model (DOM) events in your web app.
  • You can design your game to include game logic either in the web app or in the skill backend. To communicate with the skill, use the Alexa HTML API in your app.
  • Use web audio to have dynamic control over the playback of your sounds over multiple turns in the conversation.
  • If you use web audio, consider that it doesn't reduce volume by default. Be sure to listen to the voice events to reduce the volume so it doesn't interrupt your player when they're trying to speak. Also, listen to the speech events, so you can reduce the volume of web audio when Alexa is speaking
  • If your skill uses both Web API for Games and Alexa Presentation Language (APL), make sure to save any state information needed for your game. Both APL and the web app can't run on the device at the same time. You incur the startup latency cost to your web app every time you transition from APL to the web app.

For a starter project, see Alexa Web API for Games Hello World on github.com.

For a sample game project, see the My Cactus Simulation Alexa Game on github.com.

Restrictions of the HTML environment

The Web API runtime on the device disables the following browser capabilities:

  • Content URL access
  • Geolocation in the browser
  • Loading a URL from a file, file://</path>
  • Local file API
  • Local storage
  • Non-HTTP assets/URI. Web API requires HTTPS.
  • SpeechRecognition with the Web Speech API
  • Web SQL database
  • alert(), prompt(), confirm() with JavaScript
  • getUserMedia (camera, mic)

The Web API runtime on the device allows the following browser capabilities:

  • Automatic media playback
  • Cookies
  • Form data
  • History

The runtime clears cookies, form data, and history at the end of the skill session.

Last updated: Feb 13, 2023