@ada-support/ada-widget-sdk

This repository contains a JS SDK and helpful documentation for building widgets for Ada.

Usage no npm install needed!

<script type="module">
  import adaSupportAdaWidgetSdk from 'https://cdn.skypack.dev/@ada-support/ada-widget-sdk';
</script>

README

Widget SDK

This repository contains a JS SDK and helpful documentation for building widgets for Ada.

Changelog

[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:

  1. Builds metaData object consisting of information about the chatter as well as the "input data" configured on the Widget Block.
  2. 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"
});

#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"
})

Widget SDK Events

WIDGET_INITIALIZED

Properties:

  • type: WIDGET_INITIALIZED
  • widgetActive: true|false
  • metaData: A dictionary containing information about the chatter and "input date" specified on 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 chatter as well as the "inputs data" configured on the Widget Block. These can be used by the Widget to modify its behavior. For example, a Date Picker Widget Block might configure a "default date" which the Widget could use to prefill itself with.

widgetSDK.metaData

{
    chatterToken: "123",
    defaultDate: "2019-01-01"
}

Development

Install dependencies with yarn install.

Start dev server with yarn start. This will start a development server that watches for changes and will automatically reload itself when it has detected changes.

We use the html-webpack-plugin webpack plugin to provide an html page that loadins the script for testing/development purposes. The template is src/index.ejs and will compile to dist/index.html.

Serving over HTTPS

Widgets are passed sensitive details to enable communication back to api. Therefore, HTTPS is enforced on all Widgets.

During development, we get around this requirement by using ngrok:

ngrok http localhost:8100 -hostname=date-picker.widget.ngrok.io --host-header=rewrite

Tests

We use Karma + Jasmine for running tests.

Run with: yarn test

Karma will launch a Chrome browser to execute tests in.

In the future we will target IE11 using browserstack

Deploying Widget JS SDK

Coming Soon