Alexa Project Configuration

Learn how to configure your Alexa projects using the jovo.project.js file.

Introduction

The Alexa project configuration defines how the Alexa CLI plugin builds and deploys Alexa project files using the Jovo CLI. Learn more about all Alexa CLI commands here.

You can add the Alexa plugin for the Jovo CLI and its configurations to your project configuration in jovo.project.js:

const { ProjectConfig } = require('@jovotech/cli-core');
const { AlexaCli } = require('@jovotech/platform-alexa');
// ...

const project = new ProjectConfig({
  // ...
  plugins: [
    new AlexaCli({
      locales: {
        // ...
      },
      skillId: '<yourSkillId>',
      askProfile: 'default',
      endpoint: '<yourEndpoint>',
      files: {
        // ...
      },
      conversations: {
        // ...
      },
    }),
    // ...
  ],
});

The following options are currently supported:

locales: Defines how the locales in the models folder should be mapped to Alexa locales.
skillId: The Skill ID that the project should be deployed to.
askProfile: The ASK profile that should be used for the deployment.
endpoint: The endpoint to your Jovo app's code, for example on AWS Lambda.
files: This can be used to add or override files in your Alexa build folder, for example to make updates to the skill.json file.
conversations: This includes configurations for Alexa Conversations.

locales

During the build command, the Jovo Model files in the models folder get turned into Alexa Interaction Models in the build folder.

The models folder can include files for generic languages (like en) as well as localized ones (like en-US). If you use files like en.json, you need to add a mapping to the locales configuration to make sure they're translated into locales supported by Alexa (see the official Alexa documentation for supported locales).

The below example uses an en Jovo Model and creates en-US and en-GB Alexa Interaction Models:

new AlexaCli({
  locales: {
    en: ['en-US', 'en-GB'],
  },
  // ...
});

In combination with the files property, you can use the generic locales to populate publishing and privacy & compliance information in the Alexa Skill Manifest:

new AlexaCli({
  locales: {
    en: ['en-US', 'en-GB', 'en-IN'],
    de: ['de-DE'],
  },
  files: {
    'skill-package/skill.json': {
      manifest: {
        publishingInformation: {
          locales: {
            en: {
              info: "All EN locales have this"
            },
            de: {
              info: "All DE locales have this"
            }
          }
        },
        privacyAndCompliance: {
          locales: {
            'de': {
              privacyPolicyUrl: 'https://test.com/de/datenschutz/',
              termsOfUseUrl: 'https://test.com/de/agb/',
            },
            // Will be applied to en-US and en-IN
            'en': {
              privacyPolicyUrl: 'https://test.com/en/privacy/',
              termsOfUseUrl: 'https://test.com/en/tos/',
            },
            // It's still possible to add locale-specific information like below
            'en-GB': {
              privacyPolicyUrl: 'https://test-au.com/en/privacy-australia/',
              termsOfUseUrl: 'https://test-au.com/en/tos-australia/',
            },
          },
          allowsPurchases: false,
          containsAds: false,
          isChildDirected: false,
          isExportCompliant: true,
          usesPersonalInfo: false,
        },
      },
    },
  }
  // ...
});

skillId

The first time you run the deploy command for a new project, a new Alexa Skill project with a new ID is created in the Alexa Developer Console.

You can then copy the ID and add it to your project configuration like this:

new AlexaCli({
  skillId: '<yourSkillId>',
  // ...
});

This ensures that your project is always deployed to the right Skill. During the build command, the skillId is written into the build/platform.alexa/.ask/ask-states.json file, which is used during the deployment.

The skillId property can be especially helpful for staging, where different stages deploy to different Skills:

const project = new ProjectConfig({
  // ...

  defaultStage: 'dev',
  stages: {
    dev: {
      endpoint: '${JOVO_WEBHOOK_URL}',
      plugins: [
        new AlexaCli({
          skillId: '<devSkillId>',
          // ...
        }),
      ],
      // ...
    },
    prod: {
      endpoint: process.env.ENDPOINT_PROD,
      plugins: [
        new AlexaCli({
          skillId: '<prodSkillId>',
          // ...
        }),
      ],
      // ...
    },
  },
});

askProfile

You can use the Jovo CLI together with the ASK CLI to deploy to different profiles (accounts). Learn more about how to set up ASK profiles in the official Alexa docs.

You can define which profile to deploy to using the askProfile property. This is the default configuration:

new AlexaCli({
  askProfile: 'default',
  // ...
});

The askProfile property can be especially helpful for staging, where different stages deploy to different Alexa developer accounts:

const project = new ProjectConfig({
  // ...

  defaultStage: 'dev',
  stages: {
    dev: {
      endpoint: '${JOVO_WEBHOOK_URL}',
      plugins: [
        new AlexaCli({
          askProfile: '<devAskProfile>',
          // ...
        }),
      ],
      // ...
    },
    prod: {
      endpoint: process.env.ENDPOINT_PROD,
      plugins: [
        new AlexaCli({
          askProfile: '<prodAskProfile>',
          // ...
        }),
      ],
      // ...
    },
  },
});

You can also add the ASK profile as a flag in the deploy:platform command:

$ jovo deploy:platform alexa --ask-profile default

The CLI decides in the following order which ASK profile should be used:

The one passed to the CLI using the --ask-profile flag
The one in the current stage in jovo.project.js
The one in the root Alexa configuration in jovo.project.js
The default ASK profile

endpoint

The generic endpoint property can also be overridden by the Alexa CLI plugin. This is useful if you build for multiple platforms that need to use different endpoints.

new AlexaCli({
  endpoint: '<yourEndpoint>',
  // ...
});

This can be especially helpful for staging. For example, the dev stage could use the Jovo Webhook for local development, and a prod stage for Alexa could reference an ARN that points to the hosted code on AWS Lambda:

const project = new ProjectConfig({
  // ...

  defaultStage: 'dev',
  stages: {
    dev: {
      endpoint: '${JOVO_WEBHOOK_URL}',
      // ...
    },
    prod: {
      plugins: [
        new AlexaCli({
          endpoint: '<yourProdEndpoint>',
          // ...
        }),
      ],
      // ...
    },
  },
});

files

You can use the Jovo CLI File Builder to add or override files in a path of the Alexa folder in the build directory.

For example, you can make changes to the skill.json file like this:

new AlexaCli({
  files: {
    'skill-package/skill.json': {
      // Override skill.json content here
    },
  },
  // ...
});

You can add content to skill.json by using the same path of the file's content. For example, this is how you can add APL as supported interface:

new AlexaCli({
  files: {
    'skill-package/skill.json': {
      manifest: {
        apis: {
          custom: {
            interfaces: [
              {
                type: 'ALEXA_PRESENTATION_APL',
                supportedViewports: [
                  {
                    mode: 'HUB',
                    shape: 'RECTANGLE',
                    minHeight: 600,
                    maxHeight: 1279,
                    minWidth: 1280,
                    maxWidth: 1920,
                  },
                  // ...
                ],
              },
            ],
          },
        },
      },
    },
  },
  // ...
});

You can find all supported APL viewports in the official Alexa docs.