Jovo Framework Adapter

The Jargon Platform Jovo Framework Adapter (@jargon/platform-jovo) integrates the Jargon Platform SDK with voice applications built on top of the Jovo Framework.

Requirements

The Jovo Framework Adapter works with voice applicationsthat are built using version 3 of the Jovo Framework.

The minimum Node.js version is 8.10. If you're deploying your voice application on AWS Lambda all current Node.js runtimes are supported.

Installation

Using your preferred package manager (npm or yarn), use the following as the package name to add the Jargon Platform Jovo plugin as a dependency:

@jargon/platform-jovo

Initialization

After creating the Jovo application (which normally takes place in src/app.js) instantiate the Jargon plugin and register it with the application:

const { JargonPlugin } = require('@jargon/platform-jovo')
app.use(new JargonPlugin())

The Jargon plugin installs middleware that runs for every requests. That middleware adds a JovoJargon object to the jovo object that's passed to your intent handlers (as this).

Runtime interface

JovoJargon

The core class you'll work with. JovoJargon has methods that mirror the equivalent Jovo methods for constructing a response, but changes string parameters containing content presented to users to RenderItems.

/**
 * JovoJargon contains Jargon's additions to the core Jovo framework
 * class.
 */
interface JovoJargon {
  /** The resource manager for the current request */
  rm: ResourceManager

  /**
   * Add a Jargon response to the output. This response may include multiple components (speak, reprompt, etc.).
   * The response will map to an 'ask' if it contains both a speak and reprompt component.
   *
   * @param response The item to render for the response
   */
  respond (response: RenderItem): Promise<void>

  /** Responds with the given text and ends session
   * @param {RenderItem} speech The item to render for the speech content
   */
  tell (speech: RenderItem): Promise<void>

  /**
   * Says speech and waits for an answer from the user.
   * Reprompt when user input fails.
   * Keeps session open.
   * @param {RenderItem} speech The item to render for the speech content
   * @param {RenderItem} repromptSpeech The item to render for the reprompt content
   */
  ask (speech: RenderItem, repromptSpeech?: RenderItem): Promise<void>

  /** Adds a simple card to the response
   * @param {RenderItem} title The item to render for the card's title
   * @param {RenderItem} content The item to render for the card's content
   */
  showSimpleCard (title: RenderItem, content: RenderItem): Promise<void>

  /** Adds an image card to the response
   * @param {RenderItem} title The item to render for the card's title
   * @param {RenderItem} content The item to render for the card's content
   * @param {string} imageUrl The URL for the image. Must be https
   */
  showImageCard (title: RenderItem, content: RenderItem, imageUrl: string): Promise<void>
}```

### RenderItem
A RenderItem specifies a resource key, optional parameters, and options to control details of the rendering (which
are themselves optional).
```typescript
interface RenderItem {
  /** The resource key to render */
  key: string
  /** Params to use during rendering (optional) */
  params?: RenderParams
  /** Render options (optional) */
  options?: RenderOptions
}

RenderParams are a map from parameter name to a string, number, or RenderItem instance.

interface RenderParams {
  [param: string]: string | number | RenderItem
}

The use of a RenderItem instance as a parameter value makes it easy to compose multiple resource together at runtime. This is useful when a parameter value varies across locales, or when you want the SDK to select across multiple variations for a parameter value, and reduces the need to chain together multiple calls into the ResourceManager.

The ri helper function simplifies constructing a RenderItem:

function ri (key: string, params?: RenderParams, options?: RenderOptions): RenderItem

this.jargon.tell(ri('sayHello', { 'name': 'World' }))

ResourceManager

Internally JovoJargon uses a ResourceManager to render strings and objects. You can directly access the resource manager if desired, for use cases such as:

  • obtaining locale-specific values that are used as parameters for later rendering operations
  • incrementally or conditionally constructing complex content
  • response directives that internally have locale-specific content (such as an upsell directive)
  • batch rendering of multiple resources