@humany/serviceclient

@humany/serviceclient

The Service Client provides an API for interacting with classic Humany projections. A projection is a URL representing a subset of content (guides, categories, contact methods etc) in a Humany application.

Projection URL Format

The standard format of a Projection URL consists of the root application url followed by the projection name.

https://[application].humany.net/[projection-name]

Create an instance of Service Client

Create an instance by passing the Projection URL as the first constructor argument.

import { ServiceClient } from '@humany/serviceclient';

const projection = '[projection-url]';
const serviceClient = new ServiceClient(projection);

Passing additional options

The second constructor argument can be used to pass additional ServiceClientOptions.

ServiceClientOptions

Argument	Description	Type
funnel	Funnel to report statistics on.	string
client	Unique ID for the client	string
site	Site (URI) to report statistics on.	string
paging	Default paging options	object

Comments

• Funnel, Client and Site can be overriden by using the options parameter on specific API calls.

Match

Match guides based on a search phrase.

match(phrase, success, [error])

Argument	Description	Type
phrase	The phrase to match.	string
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

match(phrase, options, success, [error])

Argument	Description	Type
phrase	The phrase to match.	string
options	Additional matching options	MatchingOptions
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

MatchingOptions

Argument	Description	Type
statisticsDisabled	Whether statistics should be reported for the request.	boolean (default: false)
categoryId	Limit the matching to the specified category	number

Example

serviceClient.match('hello world', (matchResult) => {
  console.log('matched guides:', matchResult.Matches);
});

Get categories

getCategories(success, [error])

Argument	Description	Type
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

getCategories(options, success, [error])

Argument	Description	Type
options	Additional matching options	CategoriesOptions
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

CategoriesOptions

Argument	Description	Type
phrase	Get categories containging guides matching a phrase	string
categoryId	Limit the matching to the specified category	number
expand	Possible values: 'none', 'children', 'descendants'	string

Example

serviceClient.getCategories((categoryResult) => {
  console.log('all categories:', categoryResult.Children);
});

Get guide

getGuide(id, success, [error])

Argument	Description	Type
id	Guide ID.	number
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

getGuide(id, options, success, [error])

Argument	Description	Type
id	Guide ID.	number
options	Additional guide options.	GuideOptions
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

getGuide(id, connectionKey, success, [error])

Argument	Description	Type
id	Guide ID.	number
connectionKey	A connection key (part of dialog) to get.	string
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

getGuide(id, connectionKey, options, success, [error])

Argument	Description	Type
id	Guide ID.	number
connectionKey	A connection key (part of dialog) to get.	string
options	Additional guide options.	GuideOptions
success	Callback returning the result.	function
error	Callback returning a description of the error.	function

GuideOptions

Argument	Description	Type
statisticsDisabled	Whether statistics should be reported for the request.	boolean (default: false)

Comments

• If the Guide is not intended to be displayed as a result of a previous match statistics should be disabled.

Give feedback on guide

giveFeedback(id, connectionKey, feedbackType, [success, error])

Argument	Description	Type
id	Guide ID.	number
connectionKey	A connection key (part of dialog) to give feedback on.	string
feedbackType	Type of feedback to give (Positive or Negative).	string

Accessing the Service Client from a plugin

For implementations running version 4 you can author a plugin and access the current Service Client through the container under the key 'matchingClient'. The value must be resolved asynchronously as in the example below.

import { Plugin } from '@humany/widget-core';

class MyPlugin extends Plugin {
  initialize() {
    this.container.getAsync('matchingClient').then((matchingClient) => {
      // use 'matchingClient' here
    });  
  }
}

See the Skeleton Plugin repository for an example on how to author a Webprovisions plugin.