Skip to content

Latest commit

 

History

History
529 lines (389 loc) · 13.5 KB

visual.md

File metadata and controls

529 lines (389 loc) · 13.5 KB
Raw

Alexa Visual Output

Learn more about how to build Alexa Skills with visual output using the Jovo Framework.

Introduction to Visual Ouput

Visual output is used to describe or enhance the voice interaction. This ranges from simple cards, Echo Show and Echo Spot Display Templates to displaying a video.

Cards

Cards are used for the most basic cases of visual output. They can be used to display plain text and images or to ask for certain permissions (Account Linking, to-do/shopping lists, etc.) in addition to the speech output.

// @language=javascript

this.$alexaSkill.showStandardCard('Hello World', 'This is a standard card');

this.tell('I added a card to the response!');

// @language=typescript

this.$alexaSkill!.showStandardCard('Hello World', 'This is a standard card');

this.tell('I added a card to the response!');

Simple Card

The simple card can only contain plain text, which is split up into a title and content.

// @language=javascript

this.$alexaSkill.showSimpleCard('Title', 'Content');

// or

this.$alexaSkill.showCard(
    new AlexaSkill.SimpleCard()
        .setTitle('Title')
        .setContent('Content')
);

// @language=typescript

this.$alexaSkill!.showSimpleCard('Title', 'Content');

// or

this.$alexaSkill!.showCard(
    new AlexaSkill.SimpleCard()
        .setTitle('Title')
        .setContent('Content')
);

Official Amazon reference.

Standard Card

The standard card allows you to add an image in addition to the plain text, which has to be provided in two different sizes.

// @language=javascript

this.$alexaSkill.showStandardCard('Title', 'Content', {
    smallImageUrl: 'https://via.placeholder.com/720x480',
    largeImageUrl: 'https://via.placeholder.com/1200x800',
});

// or

this.$alexaSkill.showCard(
    new AlexaSkill.StandardCard()
        .setTitle('Title')
        .setText('Text')
        .setSmallImageUrl('https://via.placeholder.com/720x480')
        .setLargeImageUrl('https://via.placeholder.com/1200x800')
);

// @language=typescript

this.$alexaSkill!.showStandardCard('Title', 'Content', {
    smallImageUrl: 'https://via.placeholder.com/720x480',
    largeImageUrl: 'https://via.placeholder.com/1200x800',
});

// or

this.$alexaSkill!.showCard(
    new AlexaSkill.StandardCard()
        .setTitle('Title')
        .setText('Text')
        .setSmallImageUrl('https://via.placeholder.com/720x480')
        .setLargeImageUrl('https://via.placeholder.com/1200x800')
);

Official Amazon reference.

Display Templates

Display Templates can be used to include content on the screen of the Echo Show or Spot. There is a variety of templates, each having a different composition and features. You can find the official Amazon reference here.

To be able to use display templates for devices like Echo Show, add the following configurations to your project.js:

alexaSkill: {
  manifest: {
    apis: {
        custom: {
            interfaces: [
                {
                    type: 'RENDER_TEMPLATE'
                }
            ]
        }
    }
  }
}

Then, use the Jovo CLI to deploy to the Amazon Developer Portal:

# Build platforms folder
$ jovo build

# Upload to Alexa
$ jovo deploy

Alternatively, you can enable it in the Interfaces tab in the Amazon Developer Console:

Alexa Console: Enable Display Interface

Body Templates

Body templates are only capable of displaying images and text. There are multiple body templates, each having a different composition.

BodyTemplate1:

// @language=javascript

let bodyTemplate1 = this.$alexaSkill.templateBuilder('BodyTemplate1');

bodyTemplate1.setToken('token')
  .setTitle('Title')
  .setTextContent('Primary Text', 'Secondary Test', 'Tertiary Text');

this.$alexaSkill.showDisplayTemplate(bodyTemplate1);

// @language=typescript

let bodyTemplate1 = this.$alexaSkill!.templateBuilder('BodyTemplate1');

bodyTemplate1.setToken('token')
  .setTitle('Title')
  .setTextContent('Primary Text', 'Secondary Test', 'Tertiary Text');

this.$alexaSkill!.showDisplayTemplate(bodyTemplate1);

BodyTemplate2:

// @language=javascript

let bodyTemplate2 = this.$alexaSkill.templateBuilder('BodyTemplate2');
bodyTemplate2.setToken('token')
  .setTitle('Title')
  .setTextContent('Primary Text', 'Secondary Test', 'Tertiary Text')
  .setRightImage({
    description: 'Description',
    url: 'https://via.placeholder.com/350x150',
  });

this.$alexaSkill.showDisplayTemplate(bodyTemplate2);

// @language=typescript

let bodyTemplate2 = this.$alexaSkill!.templateBuilder('BodyTemplate2');
bodyTemplate2.setToken('token')
  .setTitle('Title')
  .setTextContent('Primary Text', 'Secondary Test', 'Tertiary Text')
  .setRightImage({
    description: 'Description',
    url: 'https://via.placeholder.com/350x150',
  });

this.$alexaSkill!.showDisplayTemplate(bodyTemplate2);

BodyTemplate3:

// @language=javascript

let bodyTemplate3 = this.$alexaSkill.templateBuilder('BodyTemplate3');

bodyTemplate3.setToken('token')
  .setTitle('Title')
  .setTextContent('Primary Text', 'Secondary Text', 'Tertiary Text')
  .setLeftImage({
    description: 'Description',
    url: 'https://via.placeholder.com/350x150',
  });

this.$alexaSkill.showDisplayTemplate(bodyTemplate3);

// @language=typescript

let bodyTemplate3 = this.$alexaSkill!.templateBuilder('BodyTemplate3');

bodyTemplate3.setToken('token')
  .setTitle('Title')
  .setTextContent('Primary Text', 'Secondary Text', 'Tertiary Text')
  .setLeftImage({
    description: 'Description',
    url: 'https://via.placeholder.com/350x150',
  });

this.$alexaSkill!.showDisplayTemplate(bodyTemplate3);

BodyTemplate6:

// @language=javascript

let bodyTemplate6 = this.$alexaSkill.templateBuilder('BodyTemplate6');

bodyTemplate6.setToken('token')
  .setTextContent('Primary Text', 'Secondary Text', 'Tertiary Text')
  .setFullScreenImage({
    description: 'Description',
    url: 'https://via.placeholder.com/1200x1000',
});

this.$alexaSkill.showDisplayTemplate(bodyTemplate6);

// @language=typescript

let bodyTemplate6 = this.$alexaSkill!.templateBuilder('BodyTemplate6');

bodyTemplate6.setToken('token')
  .setTextContent('Primary Text', 'Secondary Text', 'Tertiary Text')
  .setFullScreenImage({
    description: 'Description',
    url: 'https://via.placeholder.com/1200x1000',
});

this.$alexaSkill!.showDisplayTemplate(bodyTemplate6);

List Templates

The list template is used to display a set of scrollabe and selectable items (text and images).

ListTemplate1:

// @language=javascript

let listTemplate1 = this.$alexaSkill.templateBuilder('ListTemplate1');

listTemplate1.setTitle('Title')
  .setToken('token')
  .addItem(
    'token',
    {
      description: 'Description',
      url: 'https://via.placeholder.com/1200x1000',
    },
    'primary text',
    'secondary text',
    'tertiary text'
  ).addItem(
    'token',
    null,
    'primary text',
    'secondary text',
    'tertiary text'
  );

this.$alexaSkill.showDisplayTemplate(listTemplate1);

// @language=typescript

let listTemplate1 = this.$alexaSkill!.templateBuilder('ListTemplate1');

listTemplate1.setTitle('Title')
  .setToken('token')
  .addItem(
    'token',
    {
      description: 'Description',
      url: 'https://via.placeholder.com/1200x1000',
    },
    'primary text',
    'secondary text',
    'tertiary text'
  ).addItem(
    'token',
    null,
    'primary text',
    'secondary text',
    'tertiary text'
  );

this.$alexaSkill!.showDisplayTemplate(listTemplate1);

ListTemplate2:

// @language=javascript

let listTemplate2 = this.$alexaSkill.templateBuilder('ListTemplate2');

listTemplate2.setTitle('Title')
  .setToken('token')
  .addItem(
    'token',
    {
      description: 'Description',
      url: 'https://via.placeholder.com/1200x1000',
    },
    'primary text',
    'secondary text',
    'tertiary text'
  ).addItem(
    'token',
    null,
    'primary text',
    'secondary text',
    'tertiary text'
  );

this.$alexaSkill.showDisplayTemplate(listTemplate2);

// @language=typescript

let listTemplate2 = this.$alexaSkill!.templateBuilder('ListTemplate2');

listTemplate2.setTitle('Title')
  .setToken('token')
  .addItem(
    'token',
    {
      description: 'Description',
      url: 'https://via.placeholder.com/1200x1000',
    },
    'primary text',
    'secondary text',
    'tertiary text'
  ).addItem(
    'token',
    null,
    'primary text',
    'secondary text',
    'tertiary text'
  );

this.$alexaSkill!.showDisplayTemplate(listTemplate2);

Alexa Presentation Language

Tutorial: Using the Alexa Presentation Language (APL) with Jovo

With Jovo, you can also use the Alexa Presentation Language (APL). To add APL directives, use the following method:

// @language=javascript

this.$alexaSkill.addDirective({
        type: 'Alexa.Presentation.APL.RenderDocument',
        version: '1.0',
        document: {},
        datasources: {},
});

// @language=typescript

this.$alexaSkill!.addDirective({
        type: 'Alexa.Presentation.APL.RenderDocument',
        version: '1.0',
        document: {},
        datasources: {},
});

You can either directly add documents and data sources, or require them from JSON files:

// @language=javascript

// Example
ShowTemplateIntent() {
    // Retrieve document and data from folder
    this.$alexaSkill.addDirective({
            type: 'Alexa.Presentation.APL.RenderDocument',
            version: '1.0',
            document: require(`./path/to/document.json`),
            datasources: require(`./path/to/data-sources.json`),
    });

    this.tell(`Take a look.`);
},

// @language=typescript

// Example
ShowTemplateIntent() {
    // Retrieve document and data from folder
    this.$alexaSkill!.addDirective({
            type: 'Alexa.Presentation.APL.RenderDocument',
            version: '1.0',
            document: require(`./path/to/document.json`),
            datasources: require(`./path/to/data-sources.json`),
    });

    this.tell(`Take a look.`);
},

To enable APL, add the following configurations to your project.js:

alexaSkill: {
  manifest: {
    apis: {
        custom: {
            interfaces: [
                {
                    type: 'ALEXA_PRESENTATION_APL'
                }
            ]
        }
    }
  }
}

Then, use the Jovo CLI to deploy to the Amazon Developer Portal:

# Build platforms folder
$ jovo build

# Upload to Alexa
$ jovo deploy

Video App Interface

To launch videos on an Echo Show you can use the VideoApp interface:

// @language=javascript

this.$alexaSkill.showVideo('https://www.url.to/video.mp4', 'Any Title', 'Any Subtitle');

// @language=typescript

this.$alexaSkill!.showVideo('https://www.url.to/video.mp4', 'Any Title', 'Any Subtitle');

You can also optionally add a preamble message that Alexa will read before the video plays:

// @language=javascript

this.$alexaSkill.showVideo('https://www.url.to/video.mp4', 'Any Title', 'Any Subtitle', 'Get ready to watch your video!');

// @language=typescript

this.$alexaSkill!.showVideo('https://www.url.to/video.mp4', 'Any Title', 'Any Subtitle', 'Get ready to watch your video!');

Find the official Amazon reference here.

To enable the video app interface, add the following configurations to your project.js:

alexaSkill: {
  manifest: {
    apis: {
        custom: {
            interfaces: [
                {
                    type: 'VIDEO_APP'
                }
            ]
        }
    }
  }
}

Then, use the Jovo CLI to deploy to the Amazon Developer Portal:

# Build platforms folder
$ jovo build

# Upload to Alexa
$ jovo deploy