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 RenderItems 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.