README
Widget SDK
This repository contains a JS SDK and helpful documentation for building widgets for Ada.
Changelog
[2.2.0] - 2022-01-19
isRTL
is added to<obj>.metaData
.
[2.1.0] - 2021-12-17
brandColour
anddarkMode
are added to<obj>.metaData
.- New SDK method
#setContainerHeight
added for resizing the widget container
[2.0.1] - 2021-04-12
This version contains breaking changes.
- Security improvements around sending and receiving widget data
- Inputs and metadata are no longer parsed from query parameters in the URL
- Widget inputs are no longer included in
<obj>.metaData
, and are now found inside<obj>.widgetInputs
- The language property,
<obj>.metaData.lang
has been renamed to<obj>.metaData.language
[1.0.1] - 2021-02-02
- Widget constructor now takes
appId
as first argument, with_window
being deferred to second - Widget initialization success and failures are now being logged to Datadog, before firing the "WIDGET_INTIALIZED" and "WIDGET_INITIALIZATION_FAILED" events respectively.
[1.0.0] - 2020-07-15
#init
will now return the "WIDGET_INITIALIZED" event when the Widget is not in the "active" state. Previously,#init
would return a "WIDGET_INITIALIZATION_FAILED" event.
Widget Setup
Initialize the Widget SDK on your page by calling widgetSDK.init and registering all required callbacks.
Importing the SDK
import AdaWidgetSDK from "@ada-support/ada-widget-sdk";
const widgetSDK = new AdaWidgetSDK();
API
Widget SDK Methods
#init
Must be called before user data can be submitted.
Performs setup steps:
- Builds the
metaData
andwidgetInput
objects, consisting of information about the widget instance as well as the "input data" configured on the Widget Block respectively. - Checks whether the Widget is active or inactive (Widgets can only be used once).
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
});
#sendUserData
Used to submit user data from the Widget. Accepts a callback
that is invoked when it
completes.
Note: User data can only be sent once.
widgetSDK.sendUserData({
userSelectedData: "2019-01-01 12:00:00"
}, (event) => {
// Execute additional logic after user data is submitted.
// event.type will be one of "SEND_USER_DATA_SUCCESS" or "SEND_USER_DATA_FAILED"
})
#setContainerHeight
Used to set the height of the widget container. Expects 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.
Note: This method only applies if the widget is shown inline with the chat.
widgetSDK.setContainerHeight(document.documentElement.offsetHeight);
Widget SDK Events
WIDGET_INITIALIZED
Properties:
- type:
WIDGET_INITIALIZED
- widgetActive:
true|false
- 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:
WIDGET_INITIALIZATION_FAILED
- error: The error that caused initialization to fail (ex. a network error is encountered).
SEND_USER_DATA_SUCCESS
Properties:
- type:
SEND_USER_DATA_SUCCESS
SEND_USER_DATA_FAILED
Properties:
- type:
SEND_USER_DATA_FAILED
- error: The error that caused sendUserData to fail (ex. the Widget is not active).
Widget SDK Properties
widgetSDK.widgetIsActive
Returns boolean indicating whether Widget is "active".
A value of true
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.metaData
Returns information about the widget instance. These can be used by the Widget to modify its behavior.
widgetSDK.metaData
{
platform: "chat",
language: "en",
brandColour: "#101820",
darkMode: false,
isRTL: false,
}
platform
: 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 inbrandColour
: A hex colour string indicating the brand colour of the botdarkMode
: A boolean indicating whether or not the chat window is being viewed using a dark colour schemeisRTL
: A boolean indicating whether or not the chatter language is in a right-to-left writing system.
widgetSDK.widgetInputs
Contains 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:
widgetSDK.widgetInputs
{
dateFormat: "YY-MM-DD"
}