Tutoriel pour développeur Alexa : Comment créer une compétence Alexa multimodale

Bienvenue

Bienvenue sur Comment créer une compétence Alexa multimodale, une continuation de Cake Time: Build an Engaging Alexa Skill. Après avoir suivi ce cours, vous aurez les informations nécessaires pour créer des expériences multimodales riches pour Alexa en utilisant Alexa Presentation Language (APL). Le cours vous apprendra ce qui suit :

Module 1 : Pourquoi développer des compétences Alexa multimodales ?
Module 2 : Créez vos premiers visuels avec l'outil de création APL
Module 3 : Modifier votre backend pour ajouter des visuels LaunchRequest
Module 4 : Créez plus de visuels avec moins
Module 5 : Ajouter une animation et un contrôle vidéo
Module 6 : Conclusion et ressources

Qu'est-ce que l'heure du gâteau ?

Le cours Cake Time est un cours d'introduction au renforcement des compétences où vous pouvez créer une simple compétence Alexa (compétence Cake Time) qui se souvient de votre anniversaire. En cas d'utilisation répétée de la compétence Cake Time, vous entendrez soit un message de joyeux anniversaire d'Alexa, soit un compte à rebours de jours jusqu'à ce que ce soit votre anniversaire. Dans ce cours, nous allons ajouter des visuels et des animations pour enseigner les bases de la construction avec APL . Si vous débutez dans le développement de compétences, nous vous recommandons de consulter Cake Time: Build an Engager Alexa Skill , mais si vous développez déjà des compétences Alexa ou êtes déjà familiarisé avec les concepts, continuez à lire! Le code de la compétence Cake Time et les instructions pour configurer la compétence seront fournis plus tard dans le cours si vous en avez besoin.

Dans cette section, nous allons découvrir l'outil de création et l'utiliser pour créer un document de réponse APL LaunchRequest pour notre compétence Cake Time. À la fin de cette section, vous aurez simplement un écran qui dit « Bienvenue à Cake Time ! » avec une petite image d'un gâteau. Pour créer cet écran, vous apprendrez les éléments suivants :

Composants d'image et de texte APL
Styles
Bases de la liaison de données
Documents réactifs

Commençons.

Nous vous suggérons d'utiliser Firefox ou Chrome pour ce cours. Safari n'est pas pris en charge dans l'outil de création.

1. Bonjour l'heure du gâteau

A. Cliquez ici pour accéder à l'outil de création . Enregistrez ce lien en tant que signet, car nous le référencerons tout au long du cours.Ici, vous verrez un certain nombre de modèles.

Image de la page de destination de l'outil de création

B. Nous allons commencer avec un document vierge . Cela nous donnera un document APL de base sans aucun composant ajouté au mainTemplate.

C. Dans l'outil de création, assurez-vous que l' interface graphique est sélectionnée sur le côté gauche. Cela nous donnera la représentation graphique de la structure du document (sous Mises en page ) ainsi que des zones de texte où les propriétés peuvent être renseignées. Sur le côté droit, vous verrez les composants que vous pouvez faire glisser et déposer en place. Faites maintenant glisser un composant de texte. Vous verrez quelque chose comme ça.

D. Ajoutons du texte, "Hello Cake Time!". Cliquez sur le composant de texte sous la section des mises en page.

E. Faites défiler la partie centrale jusqu'à ce que vous trouviez le texte propriété du composant texte. Remplacez ce message par Hello Cake Time !.

F. Above this, find the fontSize property and change this to 72dp. We want to increase the text size to account for our customers which are looking at the device from far away. Now the text is outside of the blue bounding box…Uh oh! Because the text is bound to such a small rendering box, it no longer displays the text properly with such a large font. Let’s fix this.

G. Scroll down to the Width section and find the width property of our Text component. Delete the value in the width text box, so it will default to auto.

H. Do the same with height under the Height section. Auto is a better setting to use since it will automatically scale the size of the bounding box for the text to match the content. This will help us later if we choose to modify the font size in the future as we did above.

You should now see something like this.

Congratulations! You have a functioning hello caketime document. You can see the document output under the APL tab in the sidebar.

For reference here is the JSON that you should have.

{
    "type": "APL",
    "version": "1.1",
    "settings": {},
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "onMount": [],
    "graphics": {},
    "commands": {},
    "layouts": {},
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "items": [
                    {
                        "type": "Text",
                        "paddingTop": "12dp",
                        "paddingBottom": "12dp",
                        "fontSize": "72dp",
                        "text": "Hello Cake Time!"
                    }
                ],
                "height": "100%",
                "width": "100%"
            }
        ]

}
}

We created a text component and then modified some properties on it using the GUI. To see the full set of text component properties, check out the text component docs. If you looked at that page, you will see that paddingTop and paddingBottom are missing. That is because all components also inherit properties from their parents. Here is the full list of style properties that all components share.

The authoring tool also created a container for us. Containers are components that house other components in an alignment of "column" or "row". Since containers are also components, they have the basic component properties. Containers are essential for building responsive APL documents. Complex documents will use a mix of row and column containers to properly lay out components in a way which scales nicely across devices.

2. Hello Cake Time With Style

Some of the component properties can be defined using styles. Styles are a named set of properties that can be reused across components.

Not all properties can be styled on all components. Here is the full list of style-able properties for each component type.

A. Click the styles sidebar. You’ll see an empty set of parenthesis. Now, replace the empty set with this:

{
    "bigText": {
        "values": [
            {
                "fontSize": "72dp"
            }
        ]
    }
}

B. Click back into the APL tab in the sidebar and you will see your document has been updated with the styles added to the styles section.

C. Now, let’s modify the Text item to delete the fontSize property and add the following:

"style": "bigText"

Vous verrez que les propriétés sont toujours observées car elles sont maintenant tirées du style que vous avez défini. Vous pouvez tester cela en modifiant la propriété fontSize dans le bloc de style. Votre code APL ressemblera maintenant à ceci :

Allons plus loin et centrons notre texte à l'aide de styles.

D. Dans la section styles, ajoutons la propriété textAlign et définissons-la sur centered.

"textAlign": "center"

Cela vous laissera un style blob ressemblant à :

{
    "bigText": {
        "values": [
            {
                "fontSize": "72dp",
                "textAlign": "center"
            }
        ]
    }
}

Même si vous n'avez pas modifié le composant de texte réel, puisqu'il utilise le style bigText, celui-ci est maintenant appliqué au composant de texte.

3. Liaison des données

Did you notice the Data button? This simulates the data source that can be a part of the Alexa.Presentation.APL.RenderDocument directive which is what you send from your skill backend to render the document. We’ll come back to that later, but first, let’s look at how to build our document with data sources.

To reference data in a data source, you will first need to pass a parameter into your APL document. In earlier versions of APL, the entire data source was bound to a single parameter which defaulted to the name, "payload". Now, however, you can pass in multiple parameters which are defined in your data source as long as none of the parameters are called "payload". Using a parameter named "payload" reverts to this old behavior for backwards-compatibility reasons, but it is not recommended to use the legacy naming. If you look at your current APL document, you will see the default authoring tool parameter name of "payload". We will need to change this to match our data parameters. Let’s add and use a simple data source.

A. Inside the mainTemplate.parameters array, replace the word "payload" with "text". This will leave you with:

"mainTemplate": {
    "parameters": [
       "text"
    ]
   ...
}

Now that we have our parameter passed to the document, we can reference it. The data source is a JSON representation of key value pairs. We can nest this object however makes sense for our application. Now, let’s add another Text component which will use a data source and the style we defined. To reference the data, you will write an expression like, ${parameterName.YourDefinedObject}. Let’s modify our APL JSON.

B. Add the following inside the container's items array, underneath the existing text object:

{
    "type": "Text",
    "style": "bigText",
    "text": "${text.middle}"
},
{
    "type": "Text",
    "style": "bigText",
    "text": "${text.end}"
}

C. While we’re at it, let’s change the text data in our very first text component to ${text.start}. Wait a minute… Where did that go? The text disappeared because we have no data in the data source we are referencing. Let’s fix this using that Data tab.

D. After clicking the Data button, you’ll see an empty dataset {}. We'll need to add data which follows the structure we set with our parameter we named, "text". So we have a "text" object with "start", "middle", and "end" fields.

E. Add the following to the Data section of the authoring tool:

{
    "text": {
        "start": "Welcome",
        "middle": "to",
        "end": "Cake Time!"
    }
}

The data JSON object represents variable data in the document. We are going to reuse this layout later to render similarly structured text with new data. This technique will allow you to more easily localize the skill since all of the localization logic can live in the backend. In addition, we are going to leverage this functionality to reuse our APL document. You'll see the following:

bienvenue à l'image de l'heure du gâteau

Now, we have a set of reusable styles across this APL document, and we learned about making a screen using data binding. Let’s add an image of a birthday cake.

4. Adding a birthday cake

We’ll need to add an image component and use databinding. Image components use a URL to the resource that is storing the image. However, image is a primitive component. To scale the image across all of the viewport sizes would take a lot of effort and multiple image resolutions since it does not auto scale. Instead, use the AlexaImage responsive component so we can use a single image that will scale across all device resolutions.

To use the AlexaImage component, we’ll need to add an import. Imports allow you to reference layouts, styles, and resources defined in other packages. We are going to use a standard package called alexa-layouts. The import looks like this:

{
"name": "alexa-layouts",
"version": "1.1.0"
}

Add the above import object to your import list in your APL document import section. Afterwards, this will look like:

{
    "type": "APL",
    "version": "1.1",
    "settings": {},
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.1.0"
        }
    ],
...<Omitted_rest_of_doc>
}

Alexa layouts is an important package for creating responsive layouts. The AlexaImage component has many parameters, most of which are optional.

B. Add the following image block inside of a new container underneath the last text component. This new block should be nested within the existing Container, so be sure to put it in the same "items" array as your text components.

{
    "type": "AlexaImage",
    "alignSelf": "center",
    "imageSource": "${assets.cake}",
    "imageRoundedCorner": false,
    "imageScale": "best-fill",
    "imageHeight": "40vh",
    "imageAspectRatio": "square",
    "imageBlurredBackground": false
}

Décomposons ceci :

Pour les champs que nous utilisons dans AlexaImage, imageSource est important car il spécifie l'URL où l'image est hébergée.
Nous voulons lui donner le rapport hauteur/largeur standard du paysage car nous souhaitons conserver la résolution de notre image.
Lorsque l'image se met à l'échelle, elle utilisera la stratégie la mieux adaptée.
Pour contrôler la taille, nous utilisons la propriété imageHeight et la définissons à 40% de la hauteur de la fenêtre.

Pour en savoir plus sur chacun d'entre eux, consultez les paramètres dans la documentation technique . Si vous regardez les documents techniques, vous ne remarquerez aucune référence à alignSelf. Cette propriété existe et fonctionne car le composant est un composant enfant d'un conteneur. AlignSelf remplacera l'alignement du conteneur pour cet enfant uniquement. D' autres propriétés sont ajoutées car il s'agit également d'un enfant d'un conteneur. Cela repose sur un nouvel objet "assets.cake" à ajouter à la section de données. La nouvelle section de données ressemblera à :

{
    "text": {
        "start": "Bienvenue",
        "middle": "to",
        "end": "Cake Time !"
    },
    "assets": {
        "cake":"https://github.com/alexa/skill-sample-nodejs-first-apl-skill/blob/master/modules/assets/alexaCake_960x960.png?raw=true"
    }
}

C. Allez dans l' onglet Données et mettez à jour vos données avec le nouvel objet « assets ».

D. La dernière étape consiste à ajouter notre nouveau paramètre mainTemplate, "assets". Revenez à l' onglet APL et ajoutez-le à la liste mainTemplate.parameters, vous laissant avec :

"mainTemplate": {
    "parameters": [
       "text",
       "assets"
    ]
   ...
}

Then, you’ll see:

How does it look? Delicious!? This is starting to look more like a birthday-themed skill. Let’s make this work for the other viewport profiles, too.

5. Making a responsive document

Below the simulator screen that we have been viewing our changes in, you’ll see some Echo devices with screens. We have been using the "Medium Hub" device (which is the Echo Show screen parameters) for now, but there are many other supported devices. Now, let’s try out our document on other screens.

A. Click the various symbols on the top and take note of any issues you find.

The simulator device types

Small Hub [Round] (480x480)
Small Hub [Landscape] (960x480)
Medium Hub (1024x600)
Large Hub (1280x800)
Extra Large TV (1920x1080)
Add Custom Device (any x any)

The last option gives you the ability to create whichever screen resolution you want to simulate the device rendering.

WARNING: spoiler below

Figure 1. Well, that doesn’t look quite right…

B. Our wording is cut off on the Small Hub (Round) device screen. Let’s fix this using the when property. This property allows for boolean evaluation. If true, it will show a component and its children, but if false, it will not. In addition to when, we will be using Resources from the alexa-layouts import. Resources are simply named constants which are referenced with @<Resource_name>. This time, we will use the alexa-layouts package’s definitions of constants representing the above device types and viewport profiles. It allows you to create statements with predefined viewport-specific constants such as:

${@viewportProfile == @hubLandscapeLarge}

rather than

${viewport.width == "1280dp"}

There is no difference between these statements for an Echo Show 2 device request. But, let’s consider there is a new device with a 1300dp wide screen. Should we add another statement to this conditional? What about for a third device in a similar class? By using the Amazon defined resources, we will have better scaling APL documents without even knowing all the possible screen size permutations. This is because @hubLandscapeLarge represents screens between 1280 and 1920 wide, so it encompasses more devices of that class. Even though it is in the same class of device, since the screen does not match exactly the width we are checking, it will not render anything.

C. Étant donné que notre document s'affiche bien sur tous les appareils, à l'exception du petit concentrateur rond, ajoutons un nouvel ensemble de composants pour celui-ci. Cliquez sur l'icône Petit moyeu rond.

D. Étant donné qu'une fausse évaluation entraînera l'absence de composants enfants, ajoutons l'instruction suivante en haut de notre premier conteneur.

"when":"${@viewportProfile != @hubRoundSmall}"

E. Vous devriez voir un écran noir ! Vérifiez-le sur les écrans rectangulaires et vos composants seront rendus. Puisque nous avons omis la classe @hubRoundSmall de ce conteneur et de ses enfants, nous devrons créer un nouveau conteneur qui sera rendu lorsque nous serons sur un périphérique @hubRoundSmall .

F. Maintenant, sous ce premier conteneur, dupliquez le conteneur et les composants Text enfants et ajoutez-les à la liste des éléments du mainTemplate. Vous voudrez ajouter l'inverse de la déclaration ci-dessus à ce bloc :

"when":"${@viewportProfile == @hubRoundSmall}"

G. Maintenant, nous allons réparer l'affichage. Cela peut être réalisé simplement en ajoutant un peu de rembourrage en haut du premier composant de texte.

"paddingTop": "75dp",

H. Ensuite, supprimez toutes les autres valeurs de remplissage dans ces zones de texte.

I. Ensuite, retirez l'image du gâteau. Maintenant, votre écran devrait apparaître correctement sur chacun des types d'appareils. Vérifiez votre travail dans les différentes classes pour vous assurer qu'il vous convient.

J. Nous utiliserons ce JSON dans la section suivante. Enregistrez votre document APL sous le nom launchDocument.json.

Soit dit en passant, nous aurions pu corriger ce document de différentes manières pour le petit profil de moyeu rond. Nous pourrions simplement garder l'image et déposer le texte, ou déplacer l'image à l'arrière-plan du petit moyeu rond. En termes de structure, nous pourrions tout garder dans un conteneur et ajouter conditionnellement le rembourrage et masquer l'image pour offrir la même expérience. L'avantage de cette approche technique est que nous n'obtiendrons pas de nouveaux composants ajoutés par défaut à l'avenir. Ce qui signifie également que pendant que nous itérons et changeons les moyeux rectangulaires, nous ne modifierons pas la structure de nos petits écrans de moyeux ronds. Étant donné que l'écran est fondamentalement différent des autres, en particulier dans notre conception, nous l'avons bifurqué. N'hésitez pas à adopter une approche différente pour d'autres compétences si cela convient mieux à vos conceptions !

Le document APL final JSON pour référence :

{
   "type": "APL",
   "version": "1.1",
   "settings": {},
   "theme": "dark",
   "import": [
       {
           "name": "alexa-layouts",
           "version": "1.1.0"
       }
   ],
   "resources": [],
   "styles": {
       "bigText": {
           "values": [
               {
                   "fontSize": "72dp",
                   "textAlign": "center"
               }
           ]
       }
   },
   "onMount": [],
   "graphics": {},
   "commands": {},
   "layouts": {},
   "mainTemplate": {
       "parameters": [
           "text",
           "assets"
       ],
       "items": [
           {
               "type": "Container",
               "when":"${@viewportProfile != @hubRoundSmall}",
               "items": [
                   {
                       "type": "Text",
                       "style": "bigText",
                       "paddingTop": "12dp",
                       "paddingBottom": "12dp",
                       "text": "${text.start}"
                   },
                   {
                       "type": "Text",
                       "style": "bigText",
                       "paddingTop": "12dp",
                       "paddingBottom": "12dp",
                       "text": "${text.middle}"
                   },
                   {
                       "type": "Text",
                       "style": "bigText",
                       "paddingTop": "12dp",
                       "paddingBottom": "12dp",
                       "text": "${text.end}"
                   },
                   {
                       "type": "AlexaImage",
                       "alignSelf": "center",
                       "imageSource": "${assets.cake}",
                       "imageRoundedCorner": false,
                       "imageScale": "best-fill",
                       "imageHeight":"40vh",
                       "imageAspectRatio": "square",
                       "imageBlurredBackground": false
                   }
               ],
               "height": "100%",
               "width": "100%"
           },
           {
               "type": "Container",
               "when":"${@viewportProfile == @hubRoundSmall}",
               "items": [
                   {
                       "type": "Text",
                       "style": "bigText",
                       "paddingTop": "75dp",
                       "text": "${text.start}"
                   },
                   {
                       "type": "Text",
                       "style": "bigText",
                       "text": "${text.middle}"
                   },
                   {
                       "type": "Text",
                       "style": "bigText",
                       "text": "${text.end}"
                   }
               ],
               "height": "100%",
               "width": "100%"
           }
       ]
   }
}

Mettons ce document à profit dans la section suivante.

Code complet dans Github

Continuer au module 3

Rechercher dans ce blog

2👌21/2/3/4/5