Gracias por tu visita. Esta página solo está disponible en inglés.

Construct an APL document with the Authoring Tool

The APL Authoring Tool lets you build an APL document and preview how it looks. You can build a document from scratch or start from a sample template and then make changes to suit your skill.

See also Understand Alexa Presentation Language.

Open the APL authoring tool

Click https://developer.amazon.com/alexa/console/ask/displays/? to open the authoring tool page directly.

Alternatively, if you are creating or editing a skill in the developer console, click the Display link on the left to open the tool. The authoring tool page then opens in another tab.

The content you create in the authoring tool is not linked to any of your skills. To use the document you create, export the document, then use it in your skill responses that you develop in your skill service.

Start from a template

You can start from a sample template and then modify it to suit your skill.

The samples included with the authoring tool are based on the display templates that you may have used previously to build Alexa skills with screen content. For example, the Long Text Sample is similar to BodyTemplate1.

APL Authoring Tool: Long Text Sample
APL Authoring Tool: Long Text Sample
  1. Open the authoring tool (click https://developer.amazon.com/alexa/console/ask/displays/?).
  2. On the main Multimodal displays page, click one of the templates.

Each template uses a data source to provide the content displayed within the layout. Click Data JSON to see the data source. For example, BodyTemplate1 includes background images, text content, and a logo URL image reference. You can modify the content of this data JSON to see how the template displays different content.

APL Authoring Tool: Data JSON
APL Authoring Tool: Data JSON

Each template defines resources and styles that are then used within the mainTemplate for the document. To see these, look at the JSON for the full document, or open the Resources or Styles section on the lower-right panel.

Use these samples to familiarize yourself with the structure of APL by examining the components, the rendered representation at the top, and the Data JSON content. See Work with Components and Data, later, for more about navigating the authoring tool interface.

Import existing code

You can upload an existing APL document into the tool, then preview it on different devices. You can then edit the document and preview the changes. When finished, you can export a new APL document that reflects the changes.

Upload an APL document into the authoring tool

  1. Open the authoring tool (click https://developer.amazon.com/alexa/console/ask/displays/?).
  2. On the main Multimodal displays page, click Upload Code.
  3. Select the JSON file that defines the APL document you want to check.

Once the simulated screen displays, select the different devices to see an approximation of how your skill looks on different sizes.

If your document loads without errors, but you do not see any content, this is probably because the document references data in a separate data source. Upload your data as described next.

If you get an error and the tool is unable to load your document, check the format of your JSON. The authoring tool expects the document to be within a single top-level "document" property, like this (details have been removed for brevity):

{
  "document": {
    "type": "APL",
    "version": "1.1",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
      ]
    }
  }
}

Preview your document with your separate data source

APL documents often use separate data sources in order to separate the design from the data displayed. In this case, you need to also upload the JSON representing your data to the authoring tool to see the content. There are multiple ways to do this:

  • Create and upload a single JSON file with both the document and data.
  • Upload your document, then paste the JSON for the data in the authoring tool.

To upload a single file, combine the JSON for your document and your data into a single JSON file with two top-level properties: document and datasources. This is similar to the output you get when you download the code for a template from the authoring tool.

This example shows the overall structure of the file to upload (details have been removed for brevity):

{
  "document": {
    "type": "APL",
    "version": "1.1",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": []
    }
  },
  "datasources": {
    "bodyTemplate7Data": {
      "type": "object",
      "objectId": "bt7Sample",
      "title": "Today's Daily Photo of Cheese",
      "backgroundImage": {},
      "image": {},
      "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
      "hintText": "Try, \"Alexa, search for blue cheese\""
    }
  }
}

Upload this JSON as described in Upload an APL document into the authoring tool.

Alternatively, you can upload your document, then copy your data into the authoring tool separately. In this case, upload a JSON file with just one top-level document property:

{
  "document": {
    "type": "APL",
    "version": "1.1",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
      ]
    }
  }
}

After your document loads, you need to copy in your data:

  1. Click the Data JSON tab.
  2. Paste the JSON for your data source between the curly brackets {}. Note that the top-level property should be the name of your data source, not other properties such as datasources. For example, the content in the Data JSON tab should look like this:
{
  "bodyTemplate7Data": {
    "type": "object",
    "objectId": "bt7Sample",
    "title": "Today's Daily Photo of Cheese",
    "backgroundImage": {},
    "image": {},
    "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
    "hintText": "Try, \"Alexa, search for blue cheese\""
  }
}

Start from scratch

If you select "Start from scratch" on the main page, you have to create all the components and data sources yourself. See Alexa Presentation Overview for instructions on how to create your own components.

  1. Open the authoring tool (click https://developer.amazon.com/alexa/console/ask/displays/?).
  2. On the main Multimodal displays page, click Start from scratch.

Work with components and data

Once you have an APL document and data source loaded in the tool, you can see an approximate rendering of the document in the upper middle section of the screen. The components that form the layout are listed in a hierarchy in the bottom left section of the screen.

When you click a component, the corresponding component is highlighted in the rendered representation in the upper portion of the screen.

The contents of the component appear in a form in the bottom middle section, and the parameters, if any, are listed for the selected component. You can enter the values for each of the component fields, leaving out optional values if desired. The form helps guide your work and ensure that each component contains valid JSON.

APL Authoring Tool: Component Form
APL Authoring Tool: Container Form

Add, edit, and remove components

To add a component:

  1. Click the existing component that should be the parent of the component you want to add. You must select a component that can contain child components, such as a Container.
  2. Click + and enter the component information in the Add Component window.

To remove a component, select it and click the trash can icon.

When you edit a component, click to another component and then return to the original one you changed, any changes you have previously made are still present. See Export your work to save it for information about saving versions of your work.

View JSON code for the document

Use the toggle at the lower right to switch between the component view and the raw code view. In the raw code view, you can see the entire document in JSON file including all the components, and you can make edits directly. Ensure that the JSON remains valid.

APL Authoring Tool--Toggle Between Component View as Shown and Raw Code View

The Document, Resources, and Styles content associated with document can be viewed in the bottom right-hand section. Click to display the JSON content you want to view. You can edit this content, as with components in the layout. You can click in and out, and your changes are preserved. The Document content for Long Text Sample is shown in the following figure.

APL Authoring Tool: Document content
APL Authoring Tool: Document content

View your document in different viewports

As you work on your document, click the icons for the different viewports at the top of the screen to see how the document looks on different devices. You can preview with five viewports that correspond to the viewport profiles available in the viewport profiles package:

  • Small Hub (Round)
  • Small Hub (Landscape)
  • Medium Hub
  • Large Hub
  • Extra Large TV

For more about the properties of these viewports, see Alexa Viewport Profiles Package.

You can also create a custom viewport, as described later.

Icons to preview in different viewports
Icons to preview in different viewports

Create a custom viewport

You can create a custom viewport to see how your design looks on devices that are different from the five provided profiles.

  1. Click the plus icon.
  2. Change the properties of the viewport that you want to view. You can set the Shape, Pixel Width, Pixel Height, and Pixel Density. You can also indicate whether the device supports video.
  3. Click Apply.

The custom viewport remains available during your current browser session. If you close the browser and then later re-open the authoring tool, you need to re-create the custom viewport.

Simulate a device that does not support video playback

Your design needs to handle devices with screens that do not support video playback. You can create a custom viewport profile that simulates a device without video support:

  1. Create a new custom viewport.
  2. Select the Disallow Video check box.

Export your work

To save your work for later or to use in your skill code, you must export the code in a JSON file. Click the Export Code button (Export Code button ) to save the JSON.

This combines the document and data in a single JSON file with top-level document and datasources properties. You can re-import this file later to continue working on it.