User guide

Overview

While the specifics depends on the framework you're using to build your voice application, integrating the Jargon Platform SDK into your application consists of four main steps:

  1. Install the platform-specific adapter that corresponds with the framework you're using
  2. Initialize the Jargon Platform SDK when your voice application launches
  3. When handling a request, obtain a locale-specific interface for accessing your content
  4. Call render methods on that interface to obtain content, passing in any required variables

Installation and initialization

Please see the installation section for the package you're using.

Accessing content in your voice application

When handling a request, the Jargon Platform SDK provides your voice application with a framework-specific interface for accessing content. These interfaces contain render methods to access a specific kind of content (such as a structured response). The render methods take one or more RenderItem parameters that specify the key for the content to access, along with any parameters required for the SDK to render the content (based on the variables referenced in the content):

export interface RenderItem {
  /** The resource key to render */
  key: string
  /** Params to use during rendering (optional) */
  params?: RenderParams
  /** Render options (optional) */
  options?: RenderOptions
}

A RenderParams instance is an object that maps parameter names to values:

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

Note that the value of a param can in turn be a RenderItem. This allows your voice application to compose multiple pieces of content together.

The Platform SDK is fully asynchronous; it returns content to your application via a Promise. If you need to directly manipulate the content in your voice application be sure to await the return value of the render method (if using async/await), or chain onto the promise object. Framework specific adapters (such as the one for the Alexa Skill Kit) do their best to limit how often your application needs to be aware of the underlying asynchronous details.

Content sources

Local application files

Jargon Platform releases

If you're using Jargon Platform to manage and author your voice content, create a release for your project, download the release package, and unzip it into your application's resources subdirectory.

Hand-authored content files

See the file structure documentation if you wish to hand-author the content for your voice application.

Jargon Platform content distribution network

Jargon Platform customers can connect their application to Jargon's live content servers by creating a JargonRemoteResourceManagerFactory instance, and placing that instance into the options they pass to the appropriate framework specific adapter. To create a JargonRemoteResourceManagerFactory you'll need to provide the following information:

export interface JargonRemoteResourceManagerOptions {
  /** The Jargon Project ID you're requesting content for */
  projectId: string

  /** The content interface ID you're requesting content for. You can find this in the release
   * details for your deployment
   */
  contentInterfaceId: string

  /** An environment tag associated with the the content you're requesting. Note that an empty
   * string ('') corresponds to a deployment with no associated tags
   */
  tag: string

  /** The endpoint to connect to. Should come from JargonEndpoints */
  endpoint: string
}

The values for the first three items (projectId, contentInterfaceId, and tag) can be found on the Releases tab for your project. The endpoint field should use the entry in JargonEndpoints corresponding to where your application's back end is running, such as aws-us-east-1 (or the entry that is closes to your backend from a networking perspective).