alexa-toolkit v3.2.2

alexa-toolkit

deprecated

This version of the alexa-toolkit is no longer supported. Please use the v2 release found here: https://github.com/Hearst-DD/ask-toolkit or npm install ask-toolkit

Helper methods to be used in conjunction with Amazon's alexa-sdk v1.

install

npm install --save alexa-toolkit

response handlers

Creates display templates, sends tracking events (if configured), links accounts with LWA (if configured) and sends response to Alexa.

TO USE:

• index.js
  • add responseHandlers = require( "alexa-tools" ).response.handlers
  • add alexa.registerHandlers( responseHandlers, ... )

• Replace all emits to ":ask", ":askWithCard", ":tell" or ":tellWithCard" with "::ask" or "::tell"

  EXAMPLES:

  1) Replace this.emit( ":askWithCard", output, reprompt, cardTitle, card ) with this.emit( "::ask", { speech: { output: output, reprompt: reprompt }, card: { title: cardTitle, output: card } } ) 2) Replace this.emit( ":tell", output ) with this.emit( "::tell", { speech: { output: output} } )

  HANDLERS:

  1) this.emit( "::ask", askData, options) 2) this.emit( "::tell", tellData, options)

  PARAMS:

  askData = {
      card: (Card),
      speech: {
          output: (String),
          reprompt: (String)
      },
      display: (Display)
  }

  tellData = {
      card: (Card),
      speech: {
          output: (String)
      },
      display: (Display)
  }

  options = {
      outgoingIntent: {
          name: (String),
          slots: {
              (String): {
                  name: (String),
                  value: (String)
          }
      },
      saveRepeat: (Boolean) true,
      shouldEndSession: true | false | null,
      track: (Boolean) true
  }

  OBJECTS:

  Card = {
      image: {
          smallImageUrl: (URL),
          largeImageUrl: (URL)
      },
      output: (String),
      title: (String)
  }

  Display = {
     actionLinks: (Unknown),
     backButton: (Enum) HIDDEN | VISIBLE (default),
     backgroundImage: (ImageObj),
     hint: (String) | (TextObj),
     image: (ImageObj),
     list: [List],
     template: (Enum) BodyTemplate1 | BodyTemplate2 | BodyTemplate3 | BodyTemplate6 | BodyTemplate7 | ListTemplate1 | ListTemplate2,
     text: {
         primary: (TextObj),
         secondary: (TextObj),
         tertiary: (TextObj),
     },
     title: (String),
     token: (String)
  }

  ImageObj = {
      url: (URL),
      description: (String)(optional)
      height: (Int)(optional),
      width: (Int)(optional),
      size: (Enum)(optional) X_SMALL | SMALL | MEDIUM | LARGE | X_LARGE
  }

  List = {
     image: (ImageObj)
      text: {
          primary: (TextObj),
          secondary: (TextObj),
          tertiary: (TextObj),
      },
      token: (String)
  }

  TextObj = {
      type: (Enum) PlainText | RichText,
      text: (String)
  }

image specs

• BackgroundImage

  • 1024 x 600

• ListTemplate1

  • 88 x 88

• ListTemplate2
  • Portrait (192 x 280)
  • Square (280 x 280)
  • 4:3 (372 x 280)

  • 16:9 (498 x 280)

• BodyTemplate1

  • inline images only

• BodyTemplate2

  • 340 x 340

• BodyTemplate3

  • 340 x 340

• BodyTemplate6

  • 340 x 340

• BodyTemplate7

  • scalable
  • maintains aspect ratio

  Size Recommendations:

• X_SMALL: 480 x 320

• SMALL: 720 x 480
• MEDIUM: 960 x 640
• LARGE: 1200 x 800
• X_LARGE: 1920 x 1280

response utils

alexa-tools.response.utils.replaceInSpeechAndCard( responseData, replaceObj )

• Replaces all instances of replaceObj key with value of replaceObj key in responseData speech output, speech reprompt, card title and card reprompt.
• Example:

    alexa-tools.response.utils.replaceInSpeechAndCard(
        {
            speech: {
                output: "replace {foo}"
            }
        },
        {
            "{foo}": "bar"
        }
    );

  returns:

  {
      speech: {
          output: "replace bar"
      }
  }

alexa-tools.response.utils.replaceInDisplay( responseData, replaceObj )

• Replaces all instances of replaceObj key with value of replaceObj key in responseData display primary, secondary and tertiary text.
• Example:

    alexa-tools.response.utils.replaceInDisplay(
        {
            display: {
                "template": "BodyTemplate2",
                "text": {
                    "primary": {
                        "type": "RichText",
                        "text": "replace {foo}"
                    },
                    "secondary": {
                        "type": "RichText",
                        "text": "replace {foo}"
                    },
                    "tertiary": {
                        "type": "PlainText",
                        "text": "replace {foo}"
                    }
                }
            }
        },
        {
            "{foo}": "bar"
        }
    );

  returns:

  {
      display: {
         "template": "BodyTemplate2",
         "text": {
             "primary": {
                 "type": "RichText",
                 "text": "replace bar"
             },
             "secondary": {
                 "type": "RichText",
                 "text": "replace bar"
             },
             "tertiary": {
                 "type": "PlainText",
                 "text": "replace bar"
             }
         }
     }
  }

alexa-tools.response.utils.replaceInAll( responseData, replaceObj )

• Makes calls to replaceInSpeechAndCard and replaceInDisplay

analytics

• Add ANALYTICS_PROVIDER env var (default: VOICELAB)

  alexa-tools.analytics.enums.analyticsProvider = {
       DASHBOT: "dashbot",
       VOICELAB: "voicelab"
  }

• Add ANALYTICS_TOKEN env var
• index.js
  • add analytics = require( "alexa-tools" ).analytics
  • add analytics.init( event ); after Alexa instantiation.
• Use response handlers ::ask and ::tell

list-api

• Helper methods for adding items to an Alexa list

utils

• General helper methods.