@ada-support/ada-widget-sdk 中文文档教程

Question

Widget SDK

这个存储库包含一个 JS SDK 和用于为 Ada 构建小部件的有用文档。

Changelog

[2.3.0] - 2022-02-15

• Improve UI feedback for widgets rendered in sheets view.

[2.2.0] - 2022-01-19

• isRTL is added to <obj>.metaData.

[2.1.0] - 2021-12-17

• brandColour and darkMode are added to <obj>.metaData.
• New SDK method #setContainerHeight added for resizing the widget container

[2.0.1] - 2021-04-12

此版本包含重大更改。

• 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 "WIDGETINTIALIZED" and "WIDGETINITIALIZATION_FAILED" events respectively.

[1.0.0] - 2020-07-15

• #init will now return the "WIDGETINITIALIZED" event when the Widget is not in the "active" state. Previously, #init would return a "WIDGETINITIALIZATION_FAILED" event.

Widget Setup

通过调用 widgetSDK.init 并注册所有内容来初始化您页面上的 Widget SDK 需要的回调。

Importing the SDK

import AdaWidgetSDK from "@ada-support/ada-widget-sdk";
const widgetSDK = new AdaWidgetSDK();

API

Widget SDK Methods

#init

必须在提交用户数据之前调用。

执行设置步骤：

1. Builds the metaData 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).

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

用于从 Widget 提交用户数据。 接受一个 callback 当它被调用时 完成。

注意：用户数据只能发送一次。

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

用于设置小部件容器的高度。 接受以像素为单位的给定高度。 这最常用于配置小部件容器以匹配小部件内容的高度。

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

WIDGETINITIALIZATIONFAILED

Properties:

• type: WIDGET_INITIALIZATION_FAILED
• error: The error that caused initialization to fail (ex. a network error is encountered).

SENDUSERDATA_SUCCESS

Properties:

• type: SEND_USER_DATA_SUCCESS

SENDUSERDATA_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

返回指示 Widget 是否“活动”的布尔值。

true 的值表示 Widget 可用于提交用户数据。 小部件是 处于“活跃”状态。

false 的值表示小部件“不活动”或已过期并且不能再 用于提交用户数据。 Widget 应该处于“非活动”状态（即它应该 向用户明确他们不能在 Widget 上执行任何操作）。

widgetSDK.metaData

返回有关小部件实例的信息。 Widget 可以使用这些来修改其行为。

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

包含在小部件块中配置的小部件的输入。 例如， 日期选择器应用程序可以在显示选择的日期时配置自定义日期格式 追溯到用户：

widgetSDK.widgetInputs

{
    dateFormat: "YY-MM-DD"
}