This repository contains a JS SDK and helpful documentation for building widgets for Ada.
npm install @ada-support/ada-widget-sdkThis repository contains a JS SDK and helpful documentation for building widgets for Ada.
false from callback passed to #setWidgetCloseHandler no longer closes the widget automatically#setWidgetCloseHandler added for overriding widget close behaviour#sendUserData to return a promise that resolves after the input callback executes#setWidgetClose added for closing the widget container.eventsource from 1.0.7 to 1.1.1minimist from 1.2.3 to 1.2.6karma from 4.4.1 to 6.3.16url-parse from 1.4.7 to 1.5.10getContrastingBrandTextColour that is available to all widgets using the Widget SDKisRTL is added to .metaData brandColour and darkMode are added to .metaData #setContainerHeight added for resizing the widget container.metaData .widgetInputs .metaData.lang .metaData.language appId as first argument, with _window being deferred to second#init will now return the "WIDGET_INITIALIZED" event when the Widget is not in the#init would return a "WIDGET_INITIALIZATION_FAILED" event.Initialize the Widget SDK on your page by calling widgetSDK.init and registering all
required callbacks.
javascript
import AdaWidgetSDK from "@ada-support/ada-widget-sdk";
const widgetSDK = new AdaWidgetSDK();
`API
$3
####
Must be called before user data can be submitted.
Performs setup steps:
1. Builds the
and widgetInput objects, consisting of information about the widget instance as well as the
"input data" configured on the Widget Block respectively.
2. Checks whether the Widget is active or inactive (Widgets can only be used once).`javascript
widgetSDK.init((event) => {
// Perform additional setup steps in here.
// event.type will be one of "WIDGET_INITIALIZED" or "WIDGET_INITIALIZATION_FAILED"
// event.widgetInputs contains the input parameters for the widget
});
`####
Used to submit user data from the Widget. Accepts an object of data to send, and a
that
is invoked when it completes. Returns a PromiseLike which will resolve after the
given callback has run.> Note: User data can only be sent once.
`javascript
const callback = (event) => {
// Execute additional logic after user data is submitted.
// event.type will be one of "SEND_USER_DATA_SUCCESS" or "SEND_USER_DATA_FAILED"
}
await widgetSDK.sendUserData({
userSelectedData: "2019-01-01 12:00:00"
}, callback);// This code only executes after data is submitted and
callback function has executed
`####
Used to set the height of the widget container. Accepts the given height to be in pixels.
This is most commonly used to configure the widget container to match the height of the widget content.
javascript
widgetSDK.setContainerHeight(document.documentElement.offsetHeight);
`####
Used to close the widget container.
javascript
widgetSDK.setWidgetClose();
`####
Used to supply a
function to perform any cleanup when the chat user closes the sheet view.
The callback can be a regular or async function. The SDK will automatically call #setWidgetClose
after the given resolves, unless the callback returns false.> Note:
callback will only be called when a user closes the widget sheet view. It is not called if
the sheet is closed programmatically through #setWidgetClose.`javascript
widgetSDK.setWidgetCloseHandler(
async () => {
if (!widgetSDK.widgetIsActive) {
return; // Only performs cleanup if the widget is still active and interactible
} if (!confirm("Are you sure you would like to close?")) {
return false; // Prevents sheet from automatically closing
}
// Execute additional cleanup logic to perform before the sheet view tears down
}
);
`####
Checks if the brand colour contrasts with a given background enough to be used as text colour. Returns the brand colour if so; otherwise, returns a sufficiently contrasting fallback colour (black or white)
javascript
widgetSDK.getContrastingBrandTextColour(backgroundColour);
`$3
#### WIDGET_INITIALIZED
Properties:
- type:
- widgetActive:
- metaData: An object containing information about the widget instance
- widgetInput: An object containing the widget input data as configured in the Widget Block#### WIDGET_INITIALIZATION_FAILED
Properties:
- type:
- error: The error that caused initialization to fail
(ex. a network error is encountered).#### SEND_USER_DATA_SUCCESS
Properties:
- type:
#### SEND_USER_DATA_FAILED
Properties:
- type:
- error: The error that caused sendUserData to fail
(ex. the Widget is not active).$3
####
Returns boolean indicating whether Widget is "active".
A value of
indicates the Widget can be used to submit user Data. The Widget be
in an "active" state.A value of
false indicated the Widget is "inactive" or expired and can no longer be
used to submit user data. The Widget should be in an "inactive" state (ie. it should
be clear to the user that they cannot perform any action on the Widget).
####
widgetSDK.metaDataReturns information about the widget instance. These can be used by the Widget to modify its behavior.
javascript
widgetSDK.metaData{
platform: "chat",
language: "en",
brandColour: "#101820",
darkMode: false,
isRTL: false,
}
`-
: A string indicating what chat platform this widget is being displayed on (e.g. chat, messenger, etc)
- language: A language string indicating what language the chatter is speaking in
- brandColour: A hex colour string indicating the brand colour of the bot
- darkMode: A boolean indicating whether or not the chat window is being viewed using a dark colour scheme
- isRTL: A boolean indicating whether or not the chatter language is in a right-to-left writing system.####
widgetSDK.widgetInputsContains the inputs to the widget as configured in the Widget Block. For example,
the Date Picker App may be configured with a custom date format when presenting the picked
date back to the user:
javascript
widgetSDK.widgetInputs{
dateFormat: "YY-MM-DD"
}
``