Tutorial para crear un template con Alexa Presentation Language (APL) en una Skill, explicado con un ejemplo sencillo de APL. No se necesitan conocimientos previos de programación.

Qué es y qué no es APL

APL es un formato diseñado para representar elementos gráficos en los dispositivos Alexa que tengan pantalla. Dicha interfaz gráfica (GUI) acompaña a la interfaz de voz (VUI) de tu Skill y nunca sustituirla. APL está basado en JSON.

APL no está pensado para hacer aplicaciones web, aplicaciones móviles ni aplicaciones de escritorio. Estos 3 tipos de aplicaciones son capaces de ejecutar lógica en el lado del cliente. APL no. APL solo representa información visual y puede avisar al servidor de las pulsaciones del usuario en la pantalla, pero no ejecuta lógica de negocio como tal en el lado cliente. Como resultado, APL es muy sencillo y muy fácil de aprender.

Un ejemplo de pantalla APL para entenderlo todo mejor

He creado un ejemplo sencillo de interfaz con APL. Puedes descargarlo aquí. Son 4 ficheros (pero fichero 2 + fichero 3 = fichero 1):

  • 1. apl_template_export.json: Es el fichero de exportación que genera el editor online de Alexa. Nos sirve para guardar copias de nuestro trabajo mientras utilizamos el editor online. Dicho editor permite importar este fichero en el futuro para seguir editando nuestra interfaz APL.
  • 2. documentAPL.json: es un extracto del fichero «apl_template_export.json», concretamente contiene solo el valor de la propiedad «document». Este fichero sí que lo usaremos en nuestra Skill.
  • 3. datasourceAPL.json: es un extracto del fichero «apl_template_export.json», concretamente contiene solo el valor de la propiedad «datasource». Este fichero sí que lo usaremos en nuestra Skill.
  • 4. fragmento_en_lambda.js: muestra cómo modificar el backend de la Skill para incorporar APL en las respuestas.

Es decir, los ficheros 2 y 3 los genero manualmente a partir del primero, cuando el diseño APL está terminado. Así el código de la Skill queda más legible y estructurado.

 
* El diseño es horrible xD pero quería que quedase un código muy muy corto.

Los componentes de APL

En APL hay apenas 10 tipos diferentes de componentes, que combinaremos para diseñar nuestras pantallas. Algunos son componentes «finales» (Text, Image, Video) y otros componentes sirven para ordenar/anidar componentes (Container, ScrollView, Frame, Sequence, Pager, TouchWrapper). El componente «TouchWrapper» hace pulsable aquello que agrupa.

Propiedad «when» de los componentes

En cada componente podemos poner una condición que determinará si se muestra o no ese componente y todos los componentes que agrupa. Utiliza esto para hacer tu Skill multimodal (mostrando unos componentes en pantallas pequeñas y otros en pantallas grandes) o para no mostrar un campo de texto cuando el texto a mostrar es nulo:

{
"when": "${viewport.shape == 'round'}",
"type": "Container",
...
}

Uniendo Documento y Datos

Cuando nuestra Skill responda al usuario con una nueva pantalla, enviaremos por un lado el documento APL y por otro los datos. La conexión de documento y datos (data binding) la haremos en el documento con la sintaxis «${param.nombre_propiedad}». En el siguiente ejemplo, la URL de la imagen se obtiene de la propiedad «imageDeFondo» del datasource:

"mainTemplate": {
"parameters": [
"payload"
],
"items": [
{
"type": "Image",
"source": "${payload.imageDeFondo}",
...

Tamaño de los componentes

Los componentes tienen las propiedades «height» y «width» para definir su tamaño. En el ejemplo utilizo las unidades más comunes: «vh» (% sobre el alto total de la pantalla), «vw» (% sobre el ancho total de la pantalla) y «%» (% sobre el ancho o alto del contenedor del componente). También existe «px», «dp» y «auto» pero no las recomiendo; queremos interfaces que se vean bien independientemente del nº de píxeles y del tamaño de la pantalla. También están las propiedades «grow» y «shrink» de Flexbox.

Posición de los componentes

Todos los componentes tienen una propiedad «position», que puedes definir como «relative» o «absolute» (por defecto es «relative»). Si indicas «absolute», puedes utilizar las propiedades «left», «right», «top» y «bottom» para posicionar el componente con respecto a su contenedor.

También puedes utilizar las propiedades «paddingBottom», «paddingLeft», «paddingRight» y «paddingTop» para definir el espacio alrededor de un componente, pero ten en cuenta que ese espacio computa en el alto y ancho total del componente (igual que en CSS).

Diseñando nuestra primera interfaz gráfica con APL

Para diseñar pantallas con APL, recomiendo utilizar el editor online de Alexa y escoger la opción «Start from scratch». A continuación, es útil cambiar el modo de visualización para poder editar el fichero json directamente. Debe quedarte así:

En el editor online hay 2 pestañas: una para el documento y otra para el datasource. Te recomiendo que cargues el ejemplo anterior y juegues a modificarlo para ver el resultado.

Modificación del backend

Una vez tengamos terminado el diseño de la interfaz gráfica APL, hay que modificar el backend de nuestra Skill para que, detecte si el dispositivo que ha hecho la petición es compatible con APL y si lo es, contestarle con la inferfaz APL. En la respuesta APL hay que responder con el documento APL y el datasource. LAs propiedades definidas en el datasource podemos modificarlas dinámicamente antes de responder. El código de la función lambda quedaría como se muestra en el fichero «fragmento_en_lambda» del ejemplo.

Otras consideraciones

    • Para que tu Skill sea compatible con APL, debes activar esta opción desde la Consola de Desarrolladores de Alexa. Recomiendo hacer esto nada más crear tu Skill. Si tu Skill ya está publicada, deberás volver a pasar el proceso de certificación después de marcar esa casilla. No hay problema si marcas la casilla pero tu Skill aún no tiene implementada ninguna pantalla con APL.

  • Para simplificar, este ejemplo no utiliza la secciones layouts, resources y styles del documento APL. Se recomienda utilizar esto en pantallas APL más complejas, para no duplicar código. Hay más información en la documentación oficial que enlazo aquí 🙂

Para cualquier comentario o pregunta sobre el tutorial, no dudes en escribirme.

Los 4 ficheros comentados en este tutorial:

Alexa