Alexa.Presentation.APLT Interface Reference

The Alexa.Presentation.APLT interface provides directives for displaying content on a device with a character display, such as the LED 7-segment alphanumeric clock display on the Echo Dot with clock.

Alexa.Presentation.APLT in supportedInterfaces

When the user's device has a character display that supports APL, the context.System.device.supportedInterfaces object includes [Alexa.Presentation.APLT]:

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APLT": {
            "runtime": {
              "maxVersion": "1.0"
            }
          }
        }
      },
      "apiEndpoint": "https://api-amazonalexa.amazon.com",
      "apiAccessToken": ""
    },
    "Viewports": [
      {
        "id": "main",
        "type": "APLT",
        "supportedProfiles": [
          "FOUR_CHARACTER_CLOCK"
        ],
        "lineLength": 4,
        "lineCount": 1,
        "format": "SEVEN_SEGMENT",
        "interSegments": [
          {
            "x": 2,
            "y": 0,
            "characters": "':."
          }
        ]
      }
    ]
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2019-06-27T15:52:19Z",
    "locale": "en-US",
    "shouldLinkResultBeReturned": false
  }
}

Always check supportedInterfaces before returning the Alexa.Presentation.APLT directives.

RenderDocument directive

Instructs the device to display the APL content provided in the specified document. You can also optionally provide one or more datasources to bind content to document.

{
  "type": "Alexa.Presentation.APLT.RenderDocument",
  "token": "developer-provided-string",
  "targetProfile": "FOUR_CHARACTER_CLOCK",
  "document": {
    "version": "1.0",
    "type": "APLT",
    "mainTemplate": {
      "item": {
        "type": "Text",
        "id": "myTextId",
        "textAlign": "right",
        "text": "GOOd dAy",
        "overflow": "marquee"
      }
    }
  },
  "datasources": {}
}
Name Description Type Required

datasources

Map of data source objects to provide data to the document. Use this to separate your template from the data. See Data-binding Evaluation and Data-binding syntax.

Object

No

document

The APL document to display.

Object

Yes

targetProfile

The device profile to target. Set to a device profile supported by the user's device, as indicated in the request in the context.Viewports[].supportedProfiles property in the request. Since this is currently always FOUR_CHARACTER_CLOCK, you can leave this property not set.

Enum

No

token

A unique identifier for the presentation. Each document is considered an independent presentation. This is used to associate future events and directives with the appropriate presentation.

String

Yes

type

Always Alexa.Presentation.APLT.RenderDocument.

String

Yes

ExecuteCommands directive

Instructs the device to run the provided commands.

{
  "type": "Alexa.Presentation.APLT.ExecuteCommands",
  "token": "developer-provided-string",
  "commands": [
    {
      "type": "SetValue",
      "description": "Changes the text property value on the 'myTextId' component.",
      "componentId": "myTextId",
      "property": "text",
      "value": "New text value!",
      "delay": 3000
    }
  ]
}
Name Description Type Required

commands

An array of Command objects to run. Providing more than one commands is equivalent to using the Sequential command.

Array of Command

Yes

token

The unique identifier for the current presentation. Must match the token provided by the skill in the RenderDocument directive used to render the currently-displayed document.

String

Yes

type

Always Alexa.Presentation.APLT.ExecuteCommands.

String

Yes

Viewport object in the skill request

Every request sent to your skill includes information about the supported viewports for the user's device. You can use this information in your code to craft appropriate responses.

For a device with a character display, the viewport information is in the context.Viewports array. This array contains one or more viewport objects representing the supported viewports for the device. The type property indicates whether the object represents a device that supports APL for screen devices (APL) or a device that supports APL for character devices (APLT).

This example shows the Viewports array for a device with a character display:

{
  "version": "1.0",
  "session": {},
  "context": {
    "system": {
      "device": {
        "deviceId": "String",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APLT": {
            "runtime": {
              "maxVersion": "1.0"
            }
          }
        }
      }
    },
    "Viewports": [
      {
        "id": "main",
        "type": "APLT",
        "supportedProfiles": ["FOUR_CHARACTER_CLOCK"],
        "lineLength": 4,
        "lineCount": 1,
        "format": "SEVEN_SEGMENT",
        "interSegments": [
          {
            "x": 2,
            "y": 0,
            "characters": "':."
          }
        ]
      }
    ]
  },
  "request": {}
}

Properties in the viewport object:

Name Description Type

format

Shape of the characters on the display. Currently can be SEVEN_SEGMENT.

Enum

id

Unique identifier for the viewport.

String

interSegments

Array of inter-segment characters supported by the display. For example, this identifies the placement of characters such as the colon (:) in a four-character clock. See Inter-segment Characters.

Array of interSegment objects

lineCount

Height of the display in characters. A 4x1 device such as the Echo Dot with clock has a ` of 1.

Integer

lineLength

Width of the display in characters. A 4x1 device such as the Echo Dot with clock has a lineLength of 4.

Integer

supportedProfiles

A list of display types supported by the device. Currently can contain FOUR_CHARACTER_CLOCK.

Array of Enum

type

APLT for a device with a character display, APL for a device with a screen.

Enum

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces:

Was this page helpful?

Last updated: Nov 28, 2023