workwonders-sdk 0.2.3 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +208 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1 +1,209 @@
|
|
|
1
1
|
# Work Wonders SDK
|
|
2
|
+
|
|
3
|
+
This document explains how to install and use the `workwonders-sdk` in your web application. The SDK is a browser-focused widget SDK that exposes feedback and changelog widgets for your organization.
|
|
4
|
+
|
|
5
|
+
Installation with npm package
|
|
6
|
+
|
|
7
|
+
- Using npm
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install workwonders-sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
- Using pnpm
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pnpm add workwonders-sdk
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- Using yarn
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
yarn add workwonders-sdk
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Importing and initializing
|
|
26
|
+
|
|
27
|
+
The main export is the `WorkWonders` class. Create an instance and call `init` with your organization information.
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { WorkWonders } from "workwonders-sdk";
|
|
31
|
+
|
|
32
|
+
const workwonders = new WorkWonders();
|
|
33
|
+
|
|
34
|
+
await workwonders.init({
|
|
35
|
+
organization: "your-org-slug",
|
|
36
|
+
token: "optional-jwt-token",
|
|
37
|
+
locale: "en",
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- organization : required, your organization slug in WorkWonders.
|
|
42
|
+
|
|
43
|
+
- token: optional, but required for private organizations.
|
|
44
|
+
|
|
45
|
+
- locale: optional; if omitted, the SDK will pick a supported language based on your organization configuration.
|
|
46
|
+
|
|
47
|
+
After the init call is made, you will be able to initialize the feedback and changelog modules.
|
|
48
|
+
|
|
49
|
+
## Global usage via `<script>` tag
|
|
50
|
+
|
|
51
|
+
If you are not using a bundler, you can load the SDK as a browser script.
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<!DOCTYPE html>
|
|
55
|
+
<html lang="en">
|
|
56
|
+
<head>
|
|
57
|
+
<meta charset="UTF-8" />
|
|
58
|
+
<title>WorkWonders SDK Example</title>
|
|
59
|
+
<script src="https://sdk.workwonders.app/sdk.js"></script>
|
|
60
|
+
</head>
|
|
61
|
+
<body>
|
|
62
|
+
<h1>WorkWonders SDK Example</h1>
|
|
63
|
+
<script>
|
|
64
|
+
const workwonders = new window.WorkWonders();
|
|
65
|
+
workwonders
|
|
66
|
+
.init({
|
|
67
|
+
organization: "your-org-slug",
|
|
68
|
+
token: "optional-jwt-token",
|
|
69
|
+
locale: "en",
|
|
70
|
+
})
|
|
71
|
+
.then(() => {
|
|
72
|
+
console.log("WorkWonders SDK initialized");
|
|
73
|
+
});
|
|
74
|
+
</script>
|
|
75
|
+
</body>
|
|
76
|
+
</html>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Feedback widget
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import { WorkWonders } from "workwonders-sdk";
|
|
83
|
+
|
|
84
|
+
const workwonders = new WorkWonders();
|
|
85
|
+
|
|
86
|
+
await workwonders.init({
|
|
87
|
+
organization: "your-org-slug",
|
|
88
|
+
token: "optional-jwt-token",
|
|
89
|
+
locale: "en",
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
workwonders.feedback.initFeedbackWidget();
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
This will add a button that will be attached to the right side of your application.
|
|
96
|
+
|
|
97
|
+
You can customize the text of the button in this page of your organization dashboard. More customization option are planned for the future.
|
|
98
|
+
|
|
99
|
+
## Custom trigger for opening feedback
|
|
100
|
+
|
|
101
|
+
If you want to control the trigger yourself (for example, using your own button), call initFeedbackWidget with useCustomTrigger: true and then call openFeedbackWidget.
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
workwonders.feedback.initFeedbackWidget({ useCustomTrigger: true });
|
|
105
|
+
|
|
106
|
+
const button = document.getElementById("open-feedback");
|
|
107
|
+
|
|
108
|
+
button?.addEventListener("click", () => {
|
|
109
|
+
workwonders.feedback.openFeedbackWidget();
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Alternatively, you can also use the SDK’s built-in click listener by adding a data attribute to any element:
|
|
114
|
+
|
|
115
|
+
```html
|
|
116
|
+
<button data-open-workwonders-feedback>Give feedback</button>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Listening for feedback events
|
|
120
|
+
|
|
121
|
+
You can listen to FeedbackModule events:
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
workwonders.feedback.on("postSubmitted", () => {
|
|
125
|
+
console.log("Feedback post submitted");
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Changelog widget
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
import { WorkWonders } from "workwonders-sdk";
|
|
133
|
+
|
|
134
|
+
const workwonders = new WorkWonders();
|
|
135
|
+
|
|
136
|
+
await workwonders.init({
|
|
137
|
+
organization: "your-org-slug",
|
|
138
|
+
token: "optional-jwt-token",
|
|
139
|
+
locale: "en",
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
await workwonders.changelog.initChangelogWidget();
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
This will create the changelog view in your application and check if there is already some changelog that should be shown to the user.
|
|
146
|
+
|
|
147
|
+
You can also manually show some changelog using their ids:
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
workwonders.changelog.showChangelogs([1, 2, 3]);
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Or manually close the changelogs view :
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
workwonders.changelog.closeChangelogWidget();
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Mini changelog widget
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
workwonders.changelog.initChangelogWidgetMini();
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
This widget shows the last published changelogs in a list, and allows users to click and open the desired changelog
|
|
166
|
+
|
|
167
|
+
You can open the mini widget programmatically:
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
workwonders.changelog.openChangelogMiniWidget();
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Or you can rely on the global click listener and data attributes:
|
|
174
|
+
|
|
175
|
+
```html
|
|
176
|
+
<button data-open-workwonders-changelog-mini>What’s new</button>
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
To close the mini widget:
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
workwonders.changelog.closeChangelogMiniWidget();
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Context-based changelogs and SPA navigation
|
|
186
|
+
|
|
187
|
+
The SDK supports context-based changelogs, which can be shown automatically based on:
|
|
188
|
+
|
|
189
|
+
- The current URL.
|
|
190
|
+
- Optional CSS selectors for clicked elements.
|
|
191
|
+
|
|
192
|
+
On initialization, the SDK already evaluates the current context. For single-page applications, call notifyUrlChange whenever your route changes so that context-based changelogs can be re-evaluated.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
import { WorkWonders } from "workwonders-sdk";
|
|
196
|
+
|
|
197
|
+
const workwonders = new WorkWonders();
|
|
198
|
+
|
|
199
|
+
await workwonders.init({
|
|
200
|
+
organization: "your-org-slug",
|
|
201
|
+
token: "optional-jwt-token",
|
|
202
|
+
locale: "en",
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
function onRouteChange() {
|
|
206
|
+
workwonders.notifyUrlChange();
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|