Configure a Skill to Support Alexa Presentation Language (APL)

To use Alexa Presentation Language in your skill, you must add support for the Alexa.Presentation.APL interface.

Configure your skill to support the Alexa.Presentation.APL interface

Your skill must support the Alexa.Presentation.APL interface to use the APL directives and requests (RenderDocument, ExecuteCommands, and UserEvent). After you enable the interface, you can determine whether a request sent to your skill came from a device that supports APL.

You can use either the developer console or the ASK CLI to update your skill.

Configure Alexa.Presentation.APL in the developer console

  1. Open the developer console, and click Edit for the skill you want to configure.
  2. Navigate to the Build > Interfaces page.
  3. Enable the Alexa Presentation Language option.
  4. Click Save Interfaces and then Build Model to re-build your interaction model.
  5. In your skill code, determine whether the user's device supports APL before you return the APL directives.

Configure Alexa.Presentation.APL with the ASK CLI or SMAPI

With ASK CLI or SMAPI, update the manifest.apis.custom.interfaces array in your skill manifest to include an ALEXA_PRESENTATION_APL object. This object also includes the supportedViewports array, as shown here:

Copied to clipboard.

{
  "type": "ALEXA_PRESENTATION_APL",
  "supportedViewports": [
    {
      "mode": "HUB",
      "shape": "ROUND",
      "minWidth": 480,
      "maxWidth": 480,
      "minHeight": 480,
      "maxHeight": 480
    },
    {
      "mode": "HUB",
      "shape": "RECTANGLE",
      "minWidth": 1024,
      "maxWidth": 1024,
      "minHeight": 600,
      "maxHeight": 600
    },
    {
      "mode": "HUB",
      "shape": "RECTANGLE",
      "minWidth": 1280,
      "maxWidth": 1280,
      "minHeight": 800,
      "maxHeight": 800
    },
    {
      "mode": "TV",
      "shape": "RECTANGLE",
      "minWidth": 960,
      "maxWidth": 960,
      "minHeight": 540,
      "maxHeight": 540
    }
  ]
}

For more about supported viewports, see Select the Viewport Profiles Your Skill Supports.

  1. Run this command to download your skill components:
     ask api get-skill -s amzn1.ask.skill.<skillId>
    

    See Get skill subcommand.

  2. Edit the skill manifest (downloaded as skill.json) and add the ALEXA_PRESENTATION_APL object shown above to the manifest.apis.custom.interfaces array.

  3. Run this command to deploy the revised skill manifest:
     ask api update-skill -s amzn1.ask.skill.<skillId> -f skill.json
    

    See Update skill subcommand.

  4. To ensure that the update deployed correctly, repeat step #1 to download the skill manifest. Open the skill.json file in your editor and confirm that the interfaces object contains the ALEXA_PRESENTATION_APL object.

  5. In your skill code, determine whether the user's device supports APL before you return the APL directives.

For more about using the ASK CLI, see Quick Start Alexa Skills Kit Command Line Interface.

Verify that the user's device supports APL

Before your skill code sends any Alexa.Presentation.APL directives, make sure the user's device supports the Alexa.Presentation.APL interface. Check the context.System.device.supportedInterfaces object included in every request for [Alexa.Presentation.APL].

For example, this LaunchRequest is from a device that supports version 1.1 of APL (for brevity, all the request properties are not shown. For the complete schema, see request syntax:

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "1.1"
            }
          }
        }
      },
      "apiEndpoint": "https://api-amazonalexa.amazon.com",
      "apiAccessToken": ""
    },
    "Viewport": {}
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2019-06-27T15:52:19Z",
    "locale": "en-US",
    "shouldLinkResultBeReturned": false
  }
}

Use the APL directives and requests in your code

In your skill code, use the Alexa.Presentation.APL directives and requests:

  • Use the RenderDocument directive to display your content on the device.
  • Use the ExecuteCommands directive to send commands related to your document to the device.
  • Handle UserEvent requests to handle user events from the device, such as button presses.

For an overview of how APL fits into the overall skill flow, see APL and skill flow

For a simple code sample that illustrates the APL directives, see Use APL with the ASK SDK v2 for Node.js.

Do not combine the APL directives with the Display interface.

Configure Cross-Origin Resource Sharing (CORS) for resources

If your skill references external resources such as images hosted on an HTTPS endpoint, ensure that the endpoint meets these requirements:

  • The endpoint provides an SSL certificate signed by an Amazon-approved certificate authority. Many content hosting services provide this. For example, you could host your files at a service such as Amazon Simple Storage Service (Amazon S3) (an Amazon Web Services offering).
  • The endpoint must allow cross-origin resource sharing (CORS) for the images.

To enable CORS, the resource server must set the Access-Control-Allow-Origin header in its responses. To restrict the resources to just Alexa, allow just the origin be whitelisted to *.amazon.com.

If your resources are in an Amazon S3 bucket, you can configure your bucket with the following CORS configuration:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<CORSRule>
    <AllowedOrigin>*</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
</CORSRule>
</CORSConfiguration>

For more about S3 and CORS, see Enabling Cross-Origin Resource Sharing.