Device Address API Helper

This release includes a new helper class: DeviceAddressService that helps developers to better utilize the device address api.

To get user device address information, simply call one of the following functions:

DeviceAddressService.getFullAddress(deviceId, apiEndpoint, token);
DeviceAddressService.getCountryAndPostalCode(deviceID, apiEndpoint, token);

An example to get user full address information is as follows:

const Alexa = require('alexa-sdk');
'DeviceAddressIntent': function () {
        if (this.event.context.System.user.permissions) {
              let token = this.event.context.System.user.permissions.consentToken;
              let apiEndpoint = this.event.context.System.apiEndpoint;
              let deviceId = this.event.context.System.device.deviceId;

              let das = new Alexa.services.DeviceAddressService();
              das.getFullAddress(deviceId, apiEndpoint, token)
                    .then((data) => {
                             this.response.speak('<address information>');
                             console.log('Address get: ' + JSON.stringify(data));
                     })
                   .catch((error) => {
                             this.response.speak('I'm sorry. Something went wrong.');
                             console.log(error.message);
                     });
        } else {
              this.response.speak('Please grant skill permissions to access your device address.') 
        }
        this.emit(':responseReady');
}

Readme update for NamedListEvent. Minor Bug fix

This release addresses a bug found in ResponseBuilder.playVideo(source, metadata)
Now presence of metadata is checked as expected.

Permission Card Bug fixes

This release includes updates as follows:

• Adding askForPermissionsConsentCard(permissionsArray) to ResponseBuilder
• Adding askWithPermissionCard to Response

Developers now can send askForPermissionsConsentCard in the following ways:

this.emit(':askWithPermissionCard', 'outputspeech', 'reprompt', 'permissionArray');

or

this.response.speak('outputSpeech').listen('reprompt').askForPermissionsConsentCard(permissionArray);
this.emit(':responseReady');

Hotfix: DynamoDB race condition

This release reverts #127 to return :saveState to it's original behaviour to address #164

Support for Skill Events

Adds SDK support for skill events

Skill developers now have the capability to integrate with Alexa skill events directly. If the skill is subscribed to these events, the skill is notified when an event occurs. Access to these events allows skill developers to build richer skill and external app experiences. A skill event is generated whenever a customer:

• enables or disables the skill
• links or unlinks a third-party account with the skill
• grants permissions to a skill
• changes the permissions grant to the skill

Echo Show RenderTemplate / VideoPlayer / Hint support

We've extended the ResponseBuilder to support Display.RenderTemplate, Hint and VideoApp.Play directives.

• this.response.renderTemplate(template) adds a Display.RenderTemplate Directive to the response with the specified template object. See the Display.RenderTemplate reference for more information.
• this.response.hint(hintText) adds a Hint Directive to the response with the specified hintText. See the Hint Directive reference for more information
• this.response.playVideo(url, metadata) adds a VideoApp.Play directive.
  • url (string) - url to the video source. See the VideoApp Interface reference for details on supported video formats.
  • metadata ({ title : string, subtitle : string }) [optional] - specify the title and secondary title to show with the video

When you've set up your response, simply call this.emit(':responseReady'); to send your response off.

Building Echo Show templates

Template Builders are now included in alexa-sdk in the templateBuilders namespace. These provide a set of helper methods to build the JSON template for the Display.RenderTemplate directive. In the example below we use the BodyTemplate1Builder.

const Alexa = require('alexa-sdk');
// utility methods for creating Image and TextField objects
const makePlainText = Alexa.utils.TextUtils.makePlainText;
const makeImage = Alexa.utils.ImageUtils.makeImage;

// ...
'LaunchRequest' : function() {
    const builder = new Alexa.templateBuilders.BodyTemplate1Builder();

    let template = builder.setTitle('My BodyTemplate1')
                          .setBackgroundImage(makeImage('http://url/to/my/img.png'))
                          .setTextContent(makePlainText('Text content'))
                          .build();

    this.response.speak('Rendering a template!')
                 .renderTemplate(template);
    this.emit(':responseReady');
}

We've added helper utility methods to build Image and TextField objects. They are located in the Alexa.utils namespace.

const ImageUtils = require('alexa-sdk').utils.ImageUtils;

// Outputs an image with a single source
ImageUtils.makeImage(url, widthPixels, heightPixels, size, description)
/**
Outputs {
    contentDescription : '<description>'
    sources : [
        {
            url : '<url>',
            widthPixels : '<widthPixels>',
            heightPixels : '<heightPixels>',
            size : '<size>'
        }
    ]
}
*/

ImageUtils.makeImages(imgArr, description)
/**
Outputs {
    contentDescription : '<description>'
    sources : <imgArr> // array of {url, size, widthPixels, heightPixels}
}
*/


const TextUtils = require('alexa-sdk').utils.TextUtils;

TextUtils.makePlainText('my plain text field');
/**
Outputs {
    text : 'my plain text field',
    type : 'PlainText'
}
*/

TextUtils.makeRichText('my rich text field');
/**
Outputs {
    text : 'my rich text field',
    type : 'RichText'
}
*/

Building Multi-modal skills

Sending a Display.RenderTemplate directive to a headless device (like an echo) will result in an invalid directive error being thrown. To check whether a device supports a particular directive, you can check the device's supportedInterfaces property.

let handler = {
    'LaunchRequest' : function() {

        this.response.speak('Hello there');

        // Display.RenderTemplate directives can be added to the response
        if (this.event.context.System.device.supportedInterfaces.Display) {
            //... build mytemplate using TemplateBuilder
            this.response.renderTemplate(myTemplate);
        }

        this.emit(':responseReady');
    }
}

Similarly for video, you check if VideoPlayer is a supported interface of the device

let handler = {
    'PlayVideoIntent' : function() {

        // VideoApp.Play directives can be added to the response
        if (this.event.context.System.device.supportedInterfaces.VideoPlayer) {
            this.response.playVideo('http://path/to/my/video.mp4');
        } else {
            this.response.speak("The video cannot be played on your device. " +
                "To watch this video, try launching the skill from your echo show device.");
        }

        this.emit(':responseReady');
    }
}

Adding support for Display.ElementSelected events

Added support for Display.ElementSelected events.

When using a list Display.RenderTemplate. Each item in a list can be made selectable by touch. For each selectable element on the screen, the skill developer provides an associated token that they will receive in the callback response when the element is selected. See the list templates in the Display Template Reference. The developer may name the tokens using their preferred methodology.

The skill can set a token field on any selectable element, and this token is returned in a Display.ElementSelected request if that element is selected. An example of such an event is shown below.

 "request": {
    "type": "Display.ElementSelected",
    "requestId": "amzn1.echo-api.request.7zzzzzzzzz",
    "timestamp": "2017-06-06T20:05:04Z",
    "locale": "en-US",
    "token": "getTopicName-Cookie-Contest"
  }

Creating an 'ElementSelected' function in your handler will allow you to respond to these types of events. In the example below, the handler will emit a voice response with the token value that was selected.

let handler = Alexa.CreateStateHandler(STATES.start, {
    'ElementSelected': function () {
        const token = this.event.request.token; // the token of 
        this.emit(':tell', 'you clicked on an element with token ' + token);
    }
}

See the Display interface reference for more information

v1.0.10

This release adds support for the Lambda callback parameter. (Note: this is only supported in lambda functions which use NodeJS V4.3 or v6.10)

When using the callback function, lambda will wait for the event loop is empty before exiting. This is useful if you have cleanup / instrumentation or other post response activities that may not complete before this.emit(':responseReady') is called.

You can take advantage of the callback function by adding it as the third parameter when creating a new Alexa.handler()

var Alexa = require("alexa-sdk");

exports.handler = function(event, context, callback) {
    var alexa = Alexa.handler(event, context, callback);  // pass callback to the Alexa.handler
    //...
};

Lambda callback documentation: http://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html

We've also changed the this.emit(':saveState') to not call context.succeed|callback to resolve #88

Major changes:
Replace this.context.fail(error) with this._callback(error) and this.context.succeed(response) with this._callback(null, response) - Thanks @phimar
Remove context.succeed/callback calls from saveState - Thanks @knowlsie
Documentation updates - thanks @feynmanliang, @knowlsie , @katz, @muttoni, @imTachu

Adding dialog management support to SDK

v1.0.9

Adding dialog management support to SDK

Add i18n support

v1.0.6

Add i18n support.