Build Your Web App with Web API for Games

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 Web Graphics Library (WebGL).

In addition to basic JavaScript, HTML, and CSS, you can choose from a variety of WebGL renderers and JavaScript game frameworks. The following list shows some popular options:

  • React – JavaScript library that lets you compose complex UIs from small and isolated pieces of code, called components.
  • Pixi.js – Game framework and 2D graphics that uses WebGL
  • Three.js – 3D library and app framework that uses WebGL
  • Howler.js – Audio library
  • Phaser – 2D game framework for Canvas and WebGL

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

To test your game during development, run the game in a browser on your development machine and emulate the input from Alexa. Reloads after a code tweak are immediate. Most Alexa-enabled devices use Chromium for the web view, so you can expect similar desktop browsers to behave the same way. Rely on the tools in your web browser, including the debugger and console, to inspect the game state, debug state transitions and presentation timing, and more.

To debug Alexa-related code and performance bottlenecks, run your game on a target device. To get logging, run your skill on a Fire TV, and then connect to Fire TV through the Android Debug Bridge (ADB) tool. In addition, you can use the following logging strategies:

  • Add a div on top of your HTML app, and then append critical events to the div. Use this strategy to visualize messages sent to and from your endpoint and to surface error conditions.
  • Add a "heads-up display” div on top of your HTML to monitor constantly changing data. One example is the stats.js library that provides a mini heads-up display that shows frame-rate data.
  • Use a socket-based JavaScript debugging tool, such as https://remotejs.com/, that can echo your console over the internet. Use this strategy to view a large amount of logging from a specific device and to experiment with new code in the running app in real-time.
  • Echo your logging to a cloud service for later inspection. You can take advantage of the ASK SDK secure connection to your skill endpoint to send your logs as a message, and then log them as appropriate. Use this strategy to collect detailed logging from a set of devices over time, such as performance data during beta testing.

For more testing tips, see Alexa Web API debugging and performance tips.

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.
  • Set a background color or page style while your assets load to let the user know that your game is getting ready to 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, such as when you style something to look like a button. 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 tips and tricks, see Web API for Games: Tips and Tricks (January 2023 Edition).

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.

Sample code

To get started with Web API for Games, see the following projects on GitHub:

Last updated: May 03, 2023