@convokitapp/chat-embed 1.3.0 → 1.4.0
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 +40 -9
- package/dist/index.d.ts +3 -0
- package/dist/index.js +5 -1
- package/dist/main.js +7 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -25,7 +25,7 @@ from **Dashboard → your app → Chat widget**.
|
|
|
25
25
|
| Mode | Needs a backend | Who the visitor is | Use it for |
|
|
26
26
|
| --- | --- | --- | --- |
|
|
27
27
|
| `guest` | No | A new anonymous guest, resumed on return visits | Support chat, pre-sales, public sites |
|
|
28
|
-
| `uid` |
|
|
28
|
+
| `uid` | A hash from your server | The `uid` your server signed; created on first use | Signed-in users, including Shopify and other no-backend-code sites with server templates |
|
|
29
29
|
| `authToken` | Yes | The user your server verified | Logged-in users with private conversations |
|
|
30
30
|
|
|
31
31
|
### `guest`
|
|
@@ -35,26 +35,56 @@ resume token in `localStorage` (or `sessionStorage` with
|
|
|
35
35
|
`storageMode: "SESSION"`), so returning visitors keep their conversation. A
|
|
36
36
|
guest can never be made to log in as an existing user.
|
|
37
37
|
|
|
38
|
+
A resume token expires after 30 days without a visit, and rotating the widget
|
|
39
|
+
key in the dashboard invalidates every token issued before the rotation. Either
|
|
40
|
+
way the visitor starts over as a new guest; rotate the key if you suspect
|
|
41
|
+
resume tokens were copied from visitors' browsers.
|
|
42
|
+
|
|
38
43
|
### `uid`
|
|
39
44
|
|
|
45
|
+
Your server signs the user ID with the widget's **identity secret** (Dashboard →
|
|
46
|
+
your app → Chat widget) and puts the result in the page as `userHash`. Never put
|
|
47
|
+
the identity secret itself in page code.
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
ConvoKitWidget.start({ clientId, mode: "uid", widgetKey, uid: "customer_42", userHash: "<from your server>", user: { name: "Ada" } })
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`userHash` is the hex HMAC-SHA256 of the exact `uid` string:
|
|
54
|
+
|
|
40
55
|
```js
|
|
41
|
-
|
|
56
|
+
// Node
|
|
57
|
+
crypto.createHmac("sha256", process.env.CONVOKIT_IDENTITY_SECRET).update(uid).digest("hex")
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```php
|
|
61
|
+
// PHP
|
|
62
|
+
hash_hmac('sha256', $uid, getenv('CONVOKIT_IDENTITY_SECRET'));
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
# Python
|
|
67
|
+
hmac.new(secret.encode(), uid.encode(), hashlib.sha256).hexdigest()
|
|
42
68
|
```
|
|
43
69
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
> accounts. It is off by default and is enabled separately from guest mode.
|
|
70
|
+
A missing or wrong hash is refused with `INVALID_USER_HASH`, so copying the
|
|
71
|
+
public widget key is not enough to log in as someone else. Rotating the
|
|
72
|
+
identity secret in the dashboard invalidates every hash signed with the old
|
|
73
|
+
one; rotating the widget key does not change it.
|
|
49
74
|
|
|
50
|
-
Shopify example (`layout/theme.liquid
|
|
75
|
+
Shopify example (`layout/theme.liquid`, rendered on Shopify's servers), using
|
|
76
|
+
the customer when signed in. Store the secret in a theme setting, not in
|
|
77
|
+
JavaScript:
|
|
51
78
|
|
|
52
79
|
```liquid
|
|
53
80
|
{% if customer %}
|
|
81
|
+
{% assign convokit_uid = "shopify_" | append: customer.id %}
|
|
54
82
|
<script>
|
|
55
83
|
window.addEventListener("load", function () {
|
|
56
84
|
ConvoKitWidget.start({ clientId: "…", mode: "uid", widgetKey: "…",
|
|
57
|
-
uid:
|
|
85
|
+
uid: {{ convokit_uid | json }},
|
|
86
|
+
userHash: {{ convokit_uid | hmac_sha256: settings.convokit_identity_secret | json }},
|
|
87
|
+
user: { name: {{ customer.first_name | json }} },
|
|
58
88
|
startConversationWith: ["support"] });
|
|
59
89
|
});
|
|
60
90
|
</script>
|
|
@@ -83,6 +113,7 @@ pass `tokenProvider: async (appUserId) => token` instead of `tokenUrl`.
|
|
|
83
113
|
| `mode` | — | `"guest"`, `"uid"` or `"authToken"` (required). |
|
|
84
114
|
| `widgetKey` | — | Publishable key; `guest`/`uid` only. |
|
|
85
115
|
| `uid`, `user` | — | `uid` mode: the user ID, and `{ name, imageUrl }` applied on creation. |
|
|
116
|
+
| `userHash` | — | `uid` mode, required: hex HMAC-SHA256 of `uid` with the identity secret, made on your server. |
|
|
86
117
|
| `userId`, `tokenUrl` / `tokenProvider` | — | `authToken` mode. |
|
|
87
118
|
| `startConversationWith` | `[]` | User IDs to chat with. Opens the existing conversation with exactly those members, or creates it. Without it the widget shows the user's inbox. |
|
|
88
119
|
| `conversationTitle` | — | Title for a conversation the widget creates. |
|
package/dist/index.d.ts
CHANGED
|
@@ -13,6 +13,9 @@ interface WidgetConfig {
|
|
|
13
13
|
widgetKey?: string;
|
|
14
14
|
/** `uid` mode: the user to log in as, created on first use. */
|
|
15
15
|
uid?: string;
|
|
16
|
+
/** `uid` mode: hex HMAC-SHA256 of `uid` keyed with the widget's identity
|
|
17
|
+
* secret, computed on your server. Never put the secret in page code. */
|
|
18
|
+
userHash?: string;
|
|
16
19
|
/** Profile applied when the widget creates the user. */
|
|
17
20
|
user?: WidgetUserProfile;
|
|
18
21
|
/** `authToken` mode: the signed-in user's ID in your app. */
|
package/dist/index.js
CHANGED
|
@@ -17,6 +17,8 @@ function resolveConfig(input) {
|
|
|
17
17
|
if (mode !== "guest" && mode !== "uid" && mode !== "authToken") fail('mode must be "guest", "uid" or "authToken"');
|
|
18
18
|
if (mode !== "authToken" && !text(input.widgetKey)) fail(`widgetKey is required in ${mode} mode`);
|
|
19
19
|
if (mode === "uid" && !text(input.uid)) fail("uid is required in uid mode");
|
|
20
|
+
if (mode === "uid" && !/^[0-9a-f]{64}$/i.test(text(input.userHash))) fail("userHash is required in uid mode: the hex HMAC-SHA256 of uid, signed on your server with the widget identity secret");
|
|
21
|
+
if (mode !== "uid" && input.userHash !== void 0) fail("userHash is only used in uid mode");
|
|
20
22
|
if (mode === "authToken") {
|
|
21
23
|
if (!text(input.userId)) fail("userId is required in authToken mode");
|
|
22
24
|
if (!input.tokenProvider && !text(input.tokenUrl)) fail("tokenUrl or tokenProvider is required in authToken mode");
|
|
@@ -33,6 +35,7 @@ function resolveConfig(input) {
|
|
|
33
35
|
mode,
|
|
34
36
|
widgetKey: text(input.widgetKey) || void 0,
|
|
35
37
|
uid: text(input.uid) || void 0,
|
|
38
|
+
userHash: text(input.userHash) || void 0,
|
|
36
39
|
userId: text(input.userId) || void 0,
|
|
37
40
|
startConversationWith: [...new Set((input.startConversationWith ?? []).map((id) => id.trim()))],
|
|
38
41
|
isDocked: input.isDocked ?? true,
|
|
@@ -122,7 +125,7 @@ async function openWidgetSession(config, fetchImpl = fetch) {
|
|
|
122
125
|
return cachedFirst(await request(), request);
|
|
123
126
|
}
|
|
124
127
|
if (config.mode === "uid") {
|
|
125
|
-
const request = () => requestWidgetSession(config, { mode: "uid", uid: config.uid, ...profile(config) }, fetchImpl);
|
|
128
|
+
const request = () => requestWidgetSession(config, { mode: "uid", uid: config.uid, userHash: config.userHash, ...profile(config) }, fetchImpl);
|
|
126
129
|
return cachedFirst(await request(), request);
|
|
127
130
|
}
|
|
128
131
|
const tokenProvider = config.tokenProvider ?? (async (appUserId) => {
|
|
@@ -220,6 +223,7 @@ var ICONS = {
|
|
|
220
223
|
back: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m15 18-6-6 6-6"/></svg>'
|
|
221
224
|
};
|
|
222
225
|
var FRIENDLY = {
|
|
226
|
+
INVALID_USER_HASH: "This chat could not verify who you are. The site must sign the uid with its ConvoKit identity secret (userHash).",
|
|
223
227
|
WIDGET_USER_LIMIT_REACHED: "Chat is busy right now. Please try again later.",
|
|
224
228
|
PLAN_USER_LIMIT_REACHED: "Chat is busy right now. Please try again later.",
|
|
225
229
|
PLAN_UPGRADE_REQUIRED: "Chat is currently unavailable.",
|