Actions on Google Adapter¶
The Jargon Platform Actions on Google Adapter (@jargon/platform-actions-on-google
) integrates the Jargon Platform SDK with voice applications built on top of the Actions on Google client library. Both Dialogflow and Actions SDK applications are supported.
Requirements¶
The Actions on Google Adapter works with voice applications that are built using the Actions on Google v2 client library. The minimum supported version is 2.12.0.
The minimum Node.js version is 8.10. If you're deploying your voice application on Google Firebase Functions all 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 Actions on Google Adapter as a dependency:
@jargon/platform-actions-on-google
Initialization¶
JargonDialogflowApp
and JargonActionsSdkApp
are the main entry point to the Jargon SDK. You should use the version that corresponds with the API your action is written against (likely Dialogflow).
const { JargonDialogflowApp } = require('@jargon/platform-actions-on-google')
// Standard dialogflow app instantiation
const app = dialogflow()
// Install the Jargon SDK onto the application
new JargonDialogflowApp().installOnto(app)
You can configure your application to connect to the Jargon Platform content distribution network by passing an options object to the JargonPlugin
constructor with a resourceManagerFactory
value:
const { JargonDialogflowApp, JargonEndpoints, JargonRemoteResourceManagerFactory }
= require('@jargon/platform-actions-on-google')
const app = dialogflow()
const resourceManagerFactory = new JargonRemoteResourceManagerFactory({
projectId: 'JP...',
contentInterfaceId: 'JI...',
tag: '...',
endpoint: JargonEndpoints['...']
})
new JargonDialogflowApp({ resourceManagerFactory }).installOnto(app)
Runtime interface¶
The Jargon application adds middleware the extends the Conversation object passed to your intent handlers with with additional fields and methods:
// Jargon extensions to the base Actions on Google Conversation
export interface Conversation<TUserStorage> {
jargonResourceManager: ResourceManager
jrm: ResourceManager
jargonResponseFactory: ResponseFactory
jrf: ResponseFactory
jAsk (ri: RenderItem): Promise<void>
jClose (ri: RenderItem): Promise<void>
}
Jargon Responses¶
The jAsk
and jClose
methods have the same underlying semantics as the standard ask
and close
methods. Instead of taking a raw string or Actions on Google Response
the Jargon versions take a RenderItem
parameter that specifies the Jargon response to return, along with any required parameters. The Jargon Platform SDK will convert the Jargon response into the corresponding Actions on Google Response
objects (e.g., SimpleResponse
, etc.). If the Jargon response contains a reprompt jAsk
will add it to the conversation's noInputs
property.
Response Factory¶
The Jargon ResponseFactory
simplifies the creation of Actions on Google Response
objects that have user-visible string data. The Jargon ResponseFactory
provides alternative options objects that take RenderItem
s instead of raw strings. The response factory is available on the conversation object passed to your intent handlers as jrf
or jargonResponseFactory
.
export interface JBasicCardOptions {
title?: RenderItem
subtitle?: RenderItem
text?: RenderItem
image?: GoogleActionsV2UiElementsImage
buttons?: GoogleActionsV2UiElementsButton | GoogleActionsV2UiElementsButton[]
display?: GoogleActionsV2UiElementsBasicCardImageDisplayOptions
}
export interface JBrowseCarouselItemOptions {
title: RenderItem
url: string
description?: RenderItem
footer?: RenderItem
image?: GoogleActionsV2UiElementsImage
}
export interface JButtonOptions {
title: RenderItem
url?: string
action?: GoogleActionsV2UiElementsOpenUrlAction
}
export interface JImageOptions {
url: string
alt: RenderItem
height?: number
width?: number
}
export interface JLinkOutSuggestionOptions {
name: RenderItem
url: string
}
export interface JMediaObjectOptions {
url: string
description?: RenderItem
name?: RenderItem
icon?: GoogleActionsV2UiElementsImage
image?: GoogleActionsV2UiElementsImage
}
export interface JSimpleResponseOptions {
speech: RenderItem
text?: RenderItem
}
export interface JTableOptions {
title?: RenderItem
subtitle?: RenderItem
image?: GoogleActionsV2UiElementsImage
columns?: (TableColumn | string)[] | number
columnProperties?: (TableColumn | string)[]
rows: (TableRow | string[])[]
dividers?: boolean
buttons?: GoogleActionsV2UiElementsButton | GoogleActionsV2UiElementsButton[]
}
export interface JTableColumn {
header?: RenderItem
horizontalAlignment?: GoogleActionsV2UiElementsTableCardColumnPropertiesHorizontalAlignment
align?: GoogleActionsV2UiElementsTableCardColumnPropertiesHorizontalAlignment
}
export interface JTableRow {
cells?: RenderItem[]
dividerAfter?: boolean
}
export interface ResponseFactory {
basicCard (options: JBasicCardOptions): Promise<BasicCard>
browseCarouselItem (options: JBrowseCarouselItemOptions): Promise<BrowseCarouselItem>
button (options: JButtonOptions): Promise<Button>
image (options: JImageOptions): Promise<Image>
linkOutSuggestion (options: JLinkOutSuggestionOptions): Promise<LinkOutSuggestion>
mediaObject (options: JMediaObjectOptions): Promise<MediaObject>
simple (options: JSimpleResponseOptions | RenderItem): Promise<SimpleResponse>
suggestions (...suggestions: RenderItem[]): Promise<Suggestions>
table (options: JTableOptions): Promise<Table>
tableColumn (column: JTableColumn): Promise<TableColumn>
tableRow (row: JTableRow): Promise<TableRow>
}
ResourceManager¶
Internally ResponseFactory
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
- determining which variation the ResourceManager chose
The resource manager is available on the conversation object passed to your intent handlers as jrm
or jargonResourceManager
.