Platform SDK Core¶
The Platform SDK Core package (@jargon/platform-sdk-core
) is the foundation of the Jargon Platform SDK. It contains the base functionality for loading and accessing content, variant selection, and content rendering.
Installation¶
Using your preferred package manager (npm or yarn), use the following as the package name to add the Jargon Platform SDK as a dependency:
@jargon/platform-sdk-core
Initialization¶
When your application starts create a ResourceManagerFactory
:
const sdkCore = require('@jargon/platform-sdk-core');
const resourceManagerFactory = new sdkCore.DefaultResourceManagerFactory() // or sdkCore.JargonRemoteResourceManagerFactory
The ResourceManagerFactory
instance is intended to live for the lifetime of your application.
When handling a request use that factory to create a locale- and platform-specific ResourceManager
:
const resourceManager = await resourceManagerFactory.forLocaleAndPlatform('en-US', 'Alexa')
Runtime interfaces¶
RenderItem¶
A RenderItem specifies a resource key, optional parameters, and options to control details of the rendering (which are themselves optional).
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
rm.render(ri('sayHello', { 'name': 'World' }))
ResourceManager¶
ResourceManager
is the core interface for rendering locale-specific content at runtime.
export interface ResourceManager {
/** Renders a string in the current locale
* @param {RenderItem} item The item to render
* @returns {Promise<string>} A promise to the rendered string
*/
render (item: RenderItem): Promise<string>
/** Renders multiple item
* @param {RenderItem[]} items The items to render
* @returns {Promise<string[]} A promise to the rendered strings
*/
renderBatch (items: RenderItem[]): Promise<string[]>
/** Renders an object in the current locale
* @param {RenderItem} item The item to render
* @returns {Promise<T>} A promise to the rendered object
*/
renderObject<T extends object> (item: RenderItem): Promise<T>
/** Renders a response in the current locale
* @param {RenderItem} item The item to render
* @returns {Promise<ResponseVariant>} A promise to the rendered response
*/
renderResponse (item: RenderItem): Promise<ResponseVariant>
/** Retrieves information about the selected variant for a rendered item. This
* will only return a result when rendering the item required a variation
* selection. If item has been used for multiple calls to a render routine
* the result of the first operation will be returned; use selectedVariations
* to see all results.
* @param {RenderItem} item The item to retrieve the selected variant for
* @return {Promise<SelectedVariation>} A promise to the selected variation
*/
selectedVariation (item: RenderItem): Promise<SelectedVariation>
/** Retrieves information about all selected variations for rendered item. This
* will only return a result for items that required a variation selection
* during rendering. Results are ordered by the ordering of the calls to render
* routines.
* @return {Promise<SelectedVariation[]>} A promise to the selected variations
*/
selectedVariations (): Promise<SelectedVariation[]>
/** The locale the resource manager uses */
readonly locale: string
}
Note that the render routines return Promise
s to the rendered content, not the content directly.
ResourceManagerFactory¶
A ResourceManagerFactory
constructs locale-specific ResourceManager
instances.
export interface ResourceManagerFactory {
/** Constructs a ResourceManager for the specified locale and platform
* @param {string} locale The locale (such as 'en-US')
* @param {string} platform One of 'ActionsOnGoogle' | 'Alexa' | 'Bixby' | 'Siri'
*/
forLocaleAndPlatform (locale: string, platform: Platform): Promise<ResourceManager>
}
Note that forLocaleAndPlatform
returns a Promise
to the ResourceManager
.
ResourceManagerOptions¶
Options for controlling resource manager functionality. Defaults are specified in DefaultResourceManagerOptions
.
export interface ResourceManagerOptions {
/** When true (default), the resource manager will use the same random value
* when randomly selecting among variations; this ensures that calls to different routines
* (speak, reprompt, etc.) with identical RenderItem inputs will render the same output.
* When false, each render call will use a different random value, leading to possible
* inconsistencies in the final response. Note that this option can be overridden via
* a RenderItem option.
*/
consistentRandom?: boolean
/** Resource files for the provided locales will be loaded during initialization instead
* of on first use; default is none.
*/
localesToPreload?: string[]
/** When true (default), the resource manager will keep track of which variation it selected,
* allowing clients to view those selections through a call to selectedVariation(s)
*/
trackSelectedVariations?: boolean
/** The directory where resources files are stored; defaults to './resources' */
resourceDirectory?: string
}
export const DefaultResourceManagerOptions: Required<ResourceManagerOptions> = {
consistentRandom: true,
localesToPreload: [],
trackSelectedVariations: true,
resourceDirectory: './resources'
}
RenderOptions¶
Options for controlling rendering behavior, overriding the ResourceManager
s configuration.
Defaults are specified in DefaultRenderOptions
.
/**
* Options control additional rendering behavior, overriding the
* settings configured at the ResourceManager level.
*/
export interface RenderOptions {
/** When true, forces the use of a new random value for selecting variations,
* overriding consistentRandom
*/
readonly forceNewRandom?: boolean
}
export const DefaultRenderOptions: RenderOptions = {
forceNewRandom: false
}
Platform specific variants¶
A response, string, or object variant can contain optional metadata that limits its eligibility on a platform basis.
export type Platform = 'ActionsOnGoogle' | 'Alexa'
export interface VariantMetadata {
/** If present, the variant is not eligible for the listed platforms. Ignored if platforms is set. */
excludedPlatforms?: [Platform]
/** If present, the variant is only eligible for the listed platforms */
platforms?: [Platform]
}