Alexa APL 1.3 usando Ask-cli con Typescript

Una forma de hacer que tu Skill sea más atractiva de cara al usuario es añadiendo una capa de presentación visual que refuerce el diálogo con Alexa. Estamos hablando de Alexa Presentation Language (APL).

Actualmente existe la versión de APL 1.3 que incluye interesantes mejoras con respecto a las versiones anteriores:

• Componentes y templates responsive.
• Lazy Loading, que nos permite cargar progresivamente elementos en listas a medida que el usuario avanza por el contenido.
• Se simplifica el acceso a los datos.
• Nuevas propiedades: background y export. Con background podremos modificar el color de fondo, degradado, etc. Y con export podemos hacer que ciertos elementos de nuestro template puedan ser usados al importar esta template como paquete.

Activar APL

El primer paso a la hora de comenzar con APL en nuestra Skill es activar la interfaz de APL desde el manifest de nuestra Skill, el cual encontraremos en skill-package/skill.json, y añadimos la activación de la nueva interfaz en la ruta manifest.apis.custom

"interfaces": [
  {
    "type": "ALEXA_PRESENTATION_APL"
  }
]

Ahora si navegamos hasta la consola de Alexa y accedemos al menú interfaces veremos como se ha activado la opción de Alexa Presentation Language.

Alexa Presentation Language Permissions

Como podemos ver, se han seleccionado todos los dispositivos, excepto Hub Landscape Small (Echo Show 5). En este caso el formato de Hub Landscape Small es opcional, si no la seleccionamos, Alexa escala el contenido y lo ajusta al tamaño del Echo Show 5, esto no quiere decir que el resultado del redimensionado sea correcto.

Como hemos comentado Alexa por defecto selecciona esas interfaces, pero podemos especificar con más detalle en caso de que solo queramos añadir las interfaces que creamos oportunas, en este caso debemos modificar el manifest y añadir mas detalle.

{
  "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
    }
  ]
}

Como podéis comprobar están todos los formatos de Alexa excepto el formato Hub Landscape, Small del Echo 5.

Si queremos crear diseños específicos en este formato y no delegar en Alexa el renderizado de la template debemos añadir el siguiente JSON para añadir el formato de este último:

{
  "mode": "HUB",
  "shape": "RECTANGLE",
  "minWidth": 960,
  "maxWidth": 960,
  "minHeight": 480,
  "maxHeight": 480
}

Ahora sí volvemos a la consola de Alexa veremos cómo tenemos seleccionados todos los formatos.

Alexa Presentation Language Permissions

Creando nuestro primer APL

Una vez hemos activado nuestra capa de presentación toca crear nuestro primer layout de bienvenida a nuestra Skill, usaremos las herramientas que ofrece la consola de Alexa para crear una template de bienvenida.

Accedemos a través del menú “Display” y seleccionamos sobre que plantilla queremos trabajar:

Plantillas APL

Nosotros elegiremos una sencilla para que se muestre en el LaunchIntent, seleccionamos la template Short Text Sample y veréis como se carga una plantilla con datos de ejemplo.

Anteriormente esta consola de diseño tenía muchas menos opciones, ha mejorado bastante, pero en este caso explicaremos básicamente como añadir una template sin editarla.

Ejemplo de editor APL

Debemos fijarnos principalmente en el menú de la izquierda, donde tenemos dos opciones que son las que nos interesan APL y DATA.

Opciones de Menú

En la opción de menú APL, veremos un JSON con toda la estructura de nuestro template, esta plantilla hace uso de datos para cargar la información, estos datos se encuentran en el JSON dentro del menú DATA.

Ejemplo de template

Ejemplo de datasource

Podemos editarlo a nuestro gusto pero primero vamos a incorporarlo a nuestra Skill.

Cuando descarguemos nuestro diseño de APL se desacargará un solo fichero donde tendremos un JSON con el template y el datasource, nosotros lo separaremos. Buscamos el atributo donde se encuentra nuestro datasource, en nuestro caso se llama bodyTemplate6Data, y lo guardamos en un nuevo JSON llamado welcomeDS.json. Es muy importante que si modificamos el nombre del datasource, debemos modificar este nombre en el template, ya que hace referencia directa a ese nombre.

Ahora solo nos queda modificar nuestro LaunchRequestHandler, para que al iniciar la Skill nos aparezca nuestro APL.

Importamos nuestro template y datasource.

import * as template from '../apl/welcomeD.json';
import * as datasource from '../apl/welcomeDS.json';

Importante!! En typescript es posible que tengáis problemas a la hora de importar los JSONs de templates y datasources.

Error al importar JSON

Es un error que podemos solucionar de forma muy sencilla, debemos ir a nuestro fichero tsconfig.json y añadir la siguiente configuración dentro de compilerOptions:

"resolveJsonModule": true,
"esModuleInterop": true

Y el error desaparecerá.

Ahora debemos añadir una condición que comprobará si el dispositivo que invoca la Skill soporta APL.

En el caso que el dispositivo soporte APL añadimos una nueva directiva a nuestra respuesta.

Probamos y ya tenemos APL en nuestra Skill:

Ejemplo de APL de bienvenida

Ahora podéis ir probando y modificando vuestro diseño, ya veréis como cuando le cojáis el truco os resulta mucho mas fácil.