@daybook/feedback 1.5.0 → 1.6.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/LICENSE +21 -21
- package/README.md +521 -463
- package/dist/client.d.ts +5 -0
- package/dist/client.js +9 -2
- package/dist/feedback.js +10 -10
- package/dist/index.d.ts +12 -0
- package/dist/index.js +11 -0
- package/dist/module.d.ts +23 -0
- package/dist/module.js +53 -0
- package/dist/types.d.ts +4 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/widget.js +384 -384
- package/package.json +53 -46
package/README.md
CHANGED
|
@@ -1,463 +1,521 @@
|
|
|
1
|
-
# `@daybook/feedback`
|
|
2
|
-
|
|
3
|
-
In-app feedback for the web. The reporter points at what is wrong and says what happened; everything
|
|
4
|
-
a triager needs is captured without asking them.
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
//
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
pm
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
##
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
1
|
+
# `@daybook/feedback`
|
|
2
|
+
|
|
3
|
+
In-app feedback for the web. The reporter points at what is wrong and says what happened; everything
|
|
4
|
+
a triager needs is captured without asking them.
|
|
5
|
+
|
|
6
|
+
About 26 KB gzipped as a script tag. Its one dependency is `@daybook/core`, which has none.
|
|
7
|
+
|
|
8
|
+
It is a module of Daybook's SDK family for the web: the site starts `@daybook/core` once, with one key,
|
|
9
|
+
and the widget is `daybook.feedback`. Started by itself with `init({ ingestKey })`, the way before the
|
|
10
|
+
family, it works as it always has.
|
|
11
|
+
|
|
12
|
+
## Start with Daybook
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
npm install @daybook/core @daybook/feedback
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
import { Daybook } from '@daybook/core'
|
|
20
|
+
import '@daybook/feedback' // registers itself on import
|
|
21
|
+
|
|
22
|
+
const daybook = await Daybook.initialize('dbk_…', {
|
|
23
|
+
feedback: { app: { version: '1.4.0' } },
|
|
24
|
+
})
|
|
25
|
+
|
|
26
|
+
daybook.identify(user.id, { email: user.email, name: user.name }) // at sign-in
|
|
27
|
+
daybook.reset() // at sign-out
|
|
28
|
+
|
|
29
|
+
daybook.feedback.open() // from your own "Report a problem"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The widget is on the page once Daybook has started; `feedback: { autoStart: false }` keeps it off until
|
|
33
|
+
`daybook.feedback.start()`. `daybook.feedback` is the same object `init` answers, so everything below
|
|
34
|
+
is called on it, and every option below but `ingestKey` goes under `feedback`.
|
|
35
|
+
|
|
36
|
+
**The key** is the site's own, `dbk_…`: in Daybook, open the project's settings, find the site under
|
|
37
|
+
**App key** and issue one per environment. It is not a secret: it is in the page's source, and it grants
|
|
38
|
+
only what the widget does. It goes in the code where Daybook is started, never in server configuration.
|
|
39
|
+
The same key starts every Daybook module on the site.
|
|
40
|
+
|
|
41
|
+
**What turns feedback on for the site** is a web install for the same environment, in Feedback › Setup:
|
|
42
|
+
it holds the domains the widget may run on, who may report and how the widget looks. Without one the
|
|
43
|
+
widget does not appear and the console says `feedback_not_set_up`. Its own ingest key (`pmi_…`) is not
|
|
44
|
+
in the code any more.
|
|
45
|
+
|
|
46
|
+
**Who is reporting** is `daybook.identify`: the user's id is the report's `externalId`. Under verified
|
|
47
|
+
identity, pass the signature with `daybook.feedback.authenticate(signature)`; under sign-in with
|
|
48
|
+
Daybook, call `daybook.feedback.signIn()` from a click. Tracking consent does not turn feedback off: it
|
|
49
|
+
is a function of the site, not a measurement.
|
|
50
|
+
|
|
51
|
+
**By script tag**, one tag for every module:
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<script src="https://daybook.team/sdk/v1/daybook.js" data-key="dbk_…" data-modules="feedback"></script>
|
|
55
|
+
<script>
|
|
56
|
+
daybook.identify(user.id, { email: user.email })
|
|
57
|
+
</script>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`data-modules="analytics,feedback"` adds analytics with the same key. The attributes are in
|
|
61
|
+
[`@daybook/core`'s README](https://www.npmjs.com/package/@daybook/core).
|
|
62
|
+
|
|
63
|
+
The rest of this page first describes the widget started by itself, with its ingest key, which keeps
|
|
64
|
+
working.
|
|
65
|
+
|
|
66
|
+
## Install
|
|
67
|
+
|
|
68
|
+
### Script tag — no build step
|
|
69
|
+
|
|
70
|
+
```html
|
|
71
|
+
<script src="https://daybook.team/sdk/v1/feedback.js"></script>
|
|
72
|
+
<script>
|
|
73
|
+
var pm = DaybookFeedback.init({
|
|
74
|
+
ingestKey: 'pmi_…',
|
|
75
|
+
reporter: { externalId: user.id, email: user.email },
|
|
76
|
+
})
|
|
77
|
+
</script>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The `/sdk/v1/` path is versioned on purpose. A script tag points at a URL forever, so what is there
|
|
81
|
+
stays compatible with what `/ingest/v1` accepts; a breaking change would appear at `/sdk/v2/` beside
|
|
82
|
+
it rather than replacing it under everybody's feet.
|
|
83
|
+
|
|
84
|
+
### JavaScript, as a module
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
npm install @daybook/feedback
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
import { init } from '@daybook/feedback'
|
|
92
|
+
|
|
93
|
+
const pm = init({
|
|
94
|
+
ingestKey: 'pmi_…', // per-environment, write-only, safe to ship
|
|
95
|
+
app: { version: '1.4.0' },
|
|
96
|
+
reporter: { externalId: user.id, email: user.email },
|
|
97
|
+
})
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### React
|
|
101
|
+
|
|
102
|
+
Mount it once, near the root — not per route, or each navigation starts a second widget.
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
// FeedbackWidget.tsx
|
|
106
|
+
import { useEffect } from 'react'
|
|
107
|
+
import { init } from '@daybook/feedback'
|
|
108
|
+
|
|
109
|
+
export function FeedbackWidget({ user }: { user: { id: string; email: string } | null }) {
|
|
110
|
+
useEffect(() => {
|
|
111
|
+
const pm = init({
|
|
112
|
+
ingestKey: import.meta.env.VITE_FEEDBACK_KEY,
|
|
113
|
+
surface: 'web-app',
|
|
114
|
+
reporter: user ? { externalId: user.id, email: user.email } : undefined,
|
|
115
|
+
})
|
|
116
|
+
|
|
117
|
+
// Strict mode runs effects twice in development. stop() is what makes that harmless —
|
|
118
|
+
// without it you get two launchers, and the first one holds the events.
|
|
119
|
+
return () => pm.stop()
|
|
120
|
+
}, [user?.id])
|
|
121
|
+
|
|
122
|
+
return null
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Render `<FeedbackWidget user={user} />` once in your layout. It draws nothing itself: the widget
|
|
127
|
+
attaches to `document.body`, so it is not affected by a parent's `overflow` or stacking context.
|
|
128
|
+
|
|
129
|
+
### Vue
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
// useFeedback.ts
|
|
133
|
+
import { onMounted, onUnmounted, watch, type Ref } from 'vue'
|
|
134
|
+
import { init, type DaybookFeedback } from '@daybook/feedback'
|
|
135
|
+
|
|
136
|
+
export function useFeedback(user: Ref<{ id: string; email: string } | null>) {
|
|
137
|
+
let pm: DaybookFeedback | null = null
|
|
138
|
+
|
|
139
|
+
// Mounted rather than created in setup(), so it does nothing during SSR — the widget needs a
|
|
140
|
+
// document. Whoever is signed in *now* is passed to init: a watcher with `immediate: true`
|
|
141
|
+
// would fire during setup, before this runs, and identify() on nothing is silently no-op.
|
|
142
|
+
onMounted(() => {
|
|
143
|
+
pm = init({
|
|
144
|
+
ingestKey: import.meta.env.VITE_FEEDBACK_KEY,
|
|
145
|
+
surface: 'web-app',
|
|
146
|
+
reporter: user.value
|
|
147
|
+
? { externalId: user.value.id, email: user.value.email }
|
|
148
|
+
: undefined,
|
|
149
|
+
})
|
|
150
|
+
})
|
|
151
|
+
|
|
152
|
+
// identify() re-handshakes, so signing in and out is reflected without remounting — which
|
|
153
|
+
// matters because an approval granted to that person is only seen at the next handshake.
|
|
154
|
+
watch(user, next => pm?.identify(
|
|
155
|
+
next ? { externalId: next.id, email: next.email } : null))
|
|
156
|
+
|
|
157
|
+
onUnmounted(() => pm?.stop())
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Call `useFeedback(user)` once, from `App.vue`.
|
|
162
|
+
|
|
163
|
+
A launcher appears bottom-right. `F` opens the picker, `Esc` backs out, `Cmd/Ctrl+Enter` sends.
|
|
164
|
+
|
|
165
|
+
The key is the only thing you have to supply. Reports go to Daybook's own API by default — where
|
|
166
|
+
they are received is ours to keep working, not a hostname for you to paste and then keep in step
|
|
167
|
+
with us. Pass `apiUrl` only to point at something that is not Daybook: a self-hosted install, or a
|
|
168
|
+
local API while you are developing.
|
|
169
|
+
|
|
170
|
+
## Allow your domain first
|
|
171
|
+
|
|
172
|
+
The widget only runs on domains you have listed. In Daybook, open **Project settings → Feedback
|
|
173
|
+
widget**, and add your origin to an environment. That is the whole step — it works the moment you
|
|
174
|
+
save it. There is nothing to verify, because the list only ever *narrows* what a key already
|
|
175
|
+
permits: it cannot grant anyone access to anything.
|
|
176
|
+
|
|
177
|
+
`localhost` is an origin like any other. Put it on the **development** environment and you are
|
|
178
|
+
working in a minute.
|
|
179
|
+
|
|
180
|
+
**Or let your assistant do all of it.** If you have Daybook connected as an MCP server in the
|
|
181
|
+
project you are adding the widget to, `get_feedback_install` returns the package, the snippet for
|
|
182
|
+
your framework, the components you can file against, and — most usefully — a `blockers` list saying
|
|
183
|
+
what is still unconfigured. `allow_feedback_domain` and `create_feedback_key` do the two steps that
|
|
184
|
+
need doing. That path exists because the SDK fails quietly by design: without it an assistant sets
|
|
185
|
+
everything up, sees no error, and has no way to tell a working install from a silent one.
|
|
186
|
+
|
|
187
|
+
On a domain that is not listed, the handshake returns `403 origin_not_allowed` and the widget quietly
|
|
188
|
+
does not appear — which is also what it does on a revoked key and on a dead network. A feedback
|
|
189
|
+
button must never break the page it is on.
|
|
190
|
+
|
|
191
|
+
## One key, many surfaces
|
|
192
|
+
|
|
193
|
+
One key serves a whole product. Each install says which part of it it is:
|
|
194
|
+
|
|
195
|
+
```js
|
|
196
|
+
init({ ingestKey: 'pmi_…', surface: 'mobile-web' })
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`surface` is a component key from your project. The key still fixes the project and the environment
|
|
200
|
+
— the parts that must not be forgeable — so this only routes *within* a project you already write
|
|
201
|
+
to. An unknown value falls back to the key's own component rather than failing: losing the
|
|
202
|
+
attribution is not a reason to lose the report.
|
|
203
|
+
|
|
204
|
+
## Who is reporting
|
|
205
|
+
|
|
206
|
+
`init` takes a `reporter`, and `identify()` updates it once the host app knows who signed in:
|
|
207
|
+
|
|
208
|
+
```js
|
|
209
|
+
const pm = init({ … })
|
|
210
|
+
|
|
211
|
+
pm.identify({ externalId: user.id, email: user.email, name: user.name })
|
|
212
|
+
pm.identify(null) // signing out
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
That is enough for most installs. But **a browser saying who it is, is a claim** — anybody viewing
|
|
216
|
+
the page can type any address into the console. If your integration is set to require it, your
|
|
217
|
+
*backend* signs the identity:
|
|
218
|
+
|
|
219
|
+
```js
|
|
220
|
+
// On your server. The identity secret never reaches a browser.
|
|
221
|
+
const signature = crypto
|
|
222
|
+
.createHmac('sha256', process.env.DAYBOOK_IDENTITY_SECRET)
|
|
223
|
+
.update(user.id)
|
|
224
|
+
.digest('hex')
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
```js
|
|
228
|
+
// In the page, with the signature your server produced.
|
|
229
|
+
init({ …, reporter: { externalId: user.id, email: user.email }, signature })
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`pm.authenticate(signature)` sets it later, for an app that fetches it after boot.
|
|
233
|
+
|
|
234
|
+
Same shape as Intercom's and Crisp's identity verification, deliberately — if you have done one of
|
|
235
|
+
those, you have done this.
|
|
236
|
+
|
|
237
|
+
### Or sign in with Daybook
|
|
238
|
+
|
|
239
|
+
A third mode, for when the reporter already has a Daybook account — an internal tool, or your own
|
|
240
|
+
team dogfooding. Then there is no secret to configure at all:
|
|
241
|
+
|
|
242
|
+
```js
|
|
243
|
+
const pm = init({ ingestKey: 'pmi_…' })
|
|
244
|
+
|
|
245
|
+
// It opens a popup, so a real click has to trigger it — a call at startup is blocked.
|
|
246
|
+
document.querySelector('#feedback-signin')
|
|
247
|
+
?.addEventListener('click', () => pm.signIn())
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
In React, hold the instance in a `useRef` and call it from your own button's `onClick`; in Vue,
|
|
251
|
+
return `() => pm?.signIn()` from the composable. In this mode the reporter is settled by the
|
|
252
|
+
sign-in, so nothing needs `reporter` or `identify()`.
|
|
253
|
+
|
|
254
|
+
They approve a short consent screen, and we authenticate them rather than taking your word for it.
|
|
255
|
+
|
|
256
|
+
**Not for a product whose reporters are your customers.** They would have to create an account with
|
|
257
|
+
us to report a bug, which is how feedback stops arriving.
|
|
258
|
+
|
|
259
|
+
## Approval
|
|
260
|
+
|
|
261
|
+
Separately from *how* an identity is established, the integration decides *who may file*: **Open**
|
|
262
|
+
(anyone, anonymously), **Identified** (anyone who says who they are), or **Approved** (only people
|
|
263
|
+
somebody let in). Under Approved, a new reporter sees "Feedback
|
|
264
|
+
access pending approval" instead of the launcher until a maintainer approves them, and a blocked one
|
|
265
|
+
sees nothing at all.
|
|
266
|
+
|
|
267
|
+
`onReady` tells the host app which of those happened, if you would rather say it in your own words:
|
|
268
|
+
|
|
269
|
+
```js
|
|
270
|
+
init({ …, onReady: h => console.log(h.reporterStatus) }) // Approved | Pending | Blocked | Anonymous
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## What it captures
|
|
274
|
+
|
|
275
|
+
The reason this exists rather than a form: the questions that follow "it looks wrong" — which browser,
|
|
276
|
+
which build, what errored just before — are all answerable at the moment of capture, and unanswerable
|
|
277
|
+
three days later when the reporter has moved on.
|
|
278
|
+
|
|
279
|
+
- **The element**, as a CSS selector plus the click position as a fraction of that element's bounding
|
|
280
|
+
box. Not page pixels: an anchor recorded on a desktop layout has to still mean something on a phone.
|
|
281
|
+
An 80-character text snapshot comes too, so a human can find the thing after a redesign breaks the
|
|
282
|
+
selector, and the page it was on. Where nothing readable identifies the element — no test id, no
|
|
283
|
+
stable id, only generated class names — the selector falls back to its position in the tree, so a
|
|
284
|
+
pin always names an element.
|
|
285
|
+
|
|
286
|
+
**More than one, when one is not enough** (1.4). After the first pin the composer offers *Add
|
|
287
|
+
another pin*; the reporter's message, kind and files stay as they were. Pins are numbered on the
|
|
288
|
+
page, in the panel and in the screenshot, so "pin 2" in a message means something. On the wire
|
|
289
|
+
`context.anchor` is still the first pin — exactly what earlier versions sent — and
|
|
290
|
+
`context.anchors` carries all of them when there is more than one.
|
|
291
|
+
- **Page and device** — route, title, referrer, locale, timezone, viewport with DPR, and a readable
|
|
292
|
+
browser and OS rather than a raw user-agent string.
|
|
293
|
+
- **Breadcrumbs** — the last 40 navigations, clicks, console errors and failed or slow requests.
|
|
294
|
+
- **The page itself**, as `page-snapshot.json`: the markup with its classes and attributes, the
|
|
295
|
+
computed style of the pinned element and its ancestors, everything floating over the page at that
|
|
296
|
+
moment, what had focus, where the page was scrolled to, and which stylesheets were readable.
|
|
297
|
+
|
|
298
|
+
This is the half of a report a screenshot cannot give you, and it needs no permission — it is the
|
|
299
|
+
page's own state, read by script that is already running on it. A picture is for a person; most
|
|
300
|
+
feedback now passes an assistant first, and to an assistant a PNG is nearly opaque where a DOM is
|
|
301
|
+
the whole answer.
|
|
302
|
+
|
|
303
|
+
It obeys `redact` exactly as everything else does: field values are described rather than
|
|
304
|
+
reproduced, `data-daybook-private` subtrees are replaced by a marker, and credentials found in text
|
|
305
|
+
and attributes read `[masked: GitHub token]`. Whatever the reporter blurred is withheld as
|
|
306
|
+
`data-daybook-blurred`. Script bodies are dropped, attributes and text are capped, and the whole
|
|
307
|
+
thing truncates rather than growing.
|
|
308
|
+
|
|
309
|
+
**What it does carry is the page's visible text**, because that is what the page is. On screens
|
|
310
|
+
showing personal data, decide whether that belongs in a report — `dom: false` turns it off, and
|
|
311
|
+
`data-daybook-private` withholds a subtree without turning the whole thing off.
|
|
312
|
+
- **A screenshot**, if the reporter ticks "Capture the screen" and consents to the browser's share
|
|
313
|
+
prompt. The widget hides itself for the frame, so the picture is of the page underneath rather
|
|
314
|
+
than of the form that was just filled in — and every element the reporter pinned is ringed in the
|
|
315
|
+
picture, numbered when there is more than one.
|
|
316
|
+
|
|
317
|
+
The ring is the difference between a report you can act on and one you have to reconstruct. A
|
|
318
|
+
selector and a text snapshot tell you which node; they do not tell you which of the forty things
|
|
319
|
+
on that screen the sentence is about. It is drawn in the widget's own layer, never on your page:
|
|
320
|
+
no style of yours is touched, nothing reflows, and there is no undo to get wrong. The rest of the
|
|
321
|
+
page is left exactly as it was — no dimming — because the screenshot is also the record of what
|
|
322
|
+
the page looked like, and a report about a colour should not arrive with the colours changed.
|
|
323
|
+
|
|
324
|
+
Except where it must not show: private elements, credentials, and anything the reporter blurred
|
|
325
|
+
are covered before the frame is taken — see [Redaction](#redaction).
|
|
326
|
+
|
|
327
|
+
`screenshots` decides what the composer offers, and takes three values:
|
|
328
|
+
|
|
329
|
+
| Value | The composer |
|
|
330
|
+
|---|---|
|
|
331
|
+
| `true` (default) | offers the capture, ticked |
|
|
332
|
+
| `'optional'` | offers the capture, not ticked |
|
|
333
|
+
| `false` | does not offer it at all |
|
|
334
|
+
|
|
335
|
+
There is no setting that shows the control and then ignores it. A tick box that does nothing is
|
|
336
|
+
worse than no tick box.
|
|
337
|
+
|
|
338
|
+
## Where it sits
|
|
339
|
+
|
|
340
|
+
`placement` puts the widget in a corner: `bottom-right` (the default), `bottom-left`, `top-right`
|
|
341
|
+
or `top-left`. Set here it overrides the corner chosen in the workspace's own settings, which is
|
|
342
|
+
the right way round — the workspace owner is choosing a default for every install, and whoever
|
|
343
|
+
writes this line is looking at the page.
|
|
344
|
+
|
|
345
|
+
```js
|
|
346
|
+
init({ ingestKey: '...', placement: 'bottom-left' })
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
### It moves out of your other buttons' way
|
|
350
|
+
|
|
351
|
+
Most pages already have something in the bottom-right corner: a chat bubble, a back-to-top arrow,
|
|
352
|
+
a cookie notice. The widget looks at what is painted in the corner it is about to occupy and stacks
|
|
353
|
+
above it rather than on it — including things that are not there yet, like a back-to-top button that
|
|
354
|
+
appears once the reporter scrolls, which is re-checked on scroll and whenever the page changes.
|
|
355
|
+
|
|
356
|
+
There is no list of selectors involved and there will not be one: what a chat bubble and a
|
|
357
|
+
back-to-top button have in common is not a class name, it is being fixed, painted and small in the
|
|
358
|
+
corner. Anything larger than a quarter of the viewport is treated as scenery — a modal backdrop is
|
|
359
|
+
not something to politely stack above — and if getting clear would mean moving more than a third of
|
|
360
|
+
the way up the page, it stays put and overlaps instead.
|
|
361
|
+
|
|
362
|
+
Turn it off with `avoidOverlap: false` if your page positions things by measuring ours, or if the
|
|
363
|
+
movement bothers you more than the overlap would.
|
|
364
|
+
|
|
365
|
+
## Moving the panel
|
|
366
|
+
|
|
367
|
+
The composer is dragged by its header, and lands against whichever side of the window it is let go
|
|
368
|
+
nearest — only that axis pins, so dragging it to the left edge halfway down leaves it halfway down.
|
|
369
|
+
A double-click on the header puts it back.
|
|
370
|
+
|
|
371
|
+
**A drag lasts for one report.** Sending resets it, so does closing, and the next report opens where
|
|
372
|
+
`placement` says. It used to be remembered across visits, which sounds helpful and is not: the
|
|
373
|
+
widget then turns up somewhere different on every page, and the somewhere is wherever it was last
|
|
374
|
+
shoved aside — a position chosen to be temporary.
|
|
375
|
+
|
|
376
|
+
The confirmation always appears at home, never where the panel was dragged to. The reporter moved
|
|
377
|
+
the panel to see what was under it; putting the receipt back over that same spot answers a question
|
|
378
|
+
nobody asked and covers the thing they moved it for.
|
|
379
|
+
|
|
380
|
+
It closes on the cross or on Cancel, and on nothing else — not Escape, not a click on the page
|
|
381
|
+
behind it. Every one of those gestures gets pressed while a report is being written, and each of
|
|
382
|
+
them used to throw the words away.
|
|
383
|
+
|
|
384
|
+
## Redaction
|
|
385
|
+
|
|
386
|
+
On by default, and it runs before anything leaves the device — the server cannot undo a leak that has
|
|
387
|
+
already crossed the wire.
|
|
388
|
+
|
|
389
|
+
- Input values are described, never reproduced: `[7 chars]`, or `[redacted]` when the field name
|
|
390
|
+
suggests a secret.
|
|
391
|
+
- Query strings are stripped from every captured URL.
|
|
392
|
+
- Emails, JWTs, bearer tokens and long digit runs are masked in console text.
|
|
393
|
+
- Password fields and anything you mark `data-daybook-private` are blurred before a screenshot is taken.
|
|
394
|
+
- Credentials on the page are found and masked without anybody marking them (1.5) — below.
|
|
395
|
+
|
|
396
|
+
```html
|
|
397
|
+
<div data-daybook-private>Card ending 4242</div>
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Turn it off with `redact: false` only if you are certain about what is on screen. It does not turn
|
|
401
|
+
off what the reporter blurs: that was their decision, made while looking at the page.
|
|
402
|
+
|
|
403
|
+
### Credentials nobody marked
|
|
404
|
+
|
|
405
|
+
`data-daybook-private` covers what you foresaw. What nobody foresees is the settings screen that shows
|
|
406
|
+
a new API key once, a link whose query string still carries a token, a debug panel printing a JWT —
|
|
407
|
+
and the reporter, looking straight at it, rarely thinks of the key as part of the page they are
|
|
408
|
+
reporting. So the page's text, its attributes (links, `data-*`, `title`, a labelled `<meta>`), the
|
|
409
|
+
console lines, a pin's text and the page address are all read for credentials before anything is
|
|
410
|
+
sent. What is found becomes `[masked: GitHub token]` in the snapshot and a solid grey bar over
|
|
411
|
+
exactly those characters in the screenshot, and the report's `context.redaction` says how many.
|
|
412
|
+
|
|
413
|
+
Recognised on their own, because their prefix is not something prose contains for any other reason:
|
|
414
|
+
|
|
415
|
+
| | |
|
|
416
|
+
|---|---|
|
|
417
|
+
| Daybook API keys | `pmk_` and 64 hex characters |
|
|
418
|
+
| OpenAI, Anthropic | `sk-…`, `sk-proj-…`, `sk-ant-…` with a generated body |
|
|
419
|
+
| Stripe | `sk_live_…`, `sk_test_…`, `rk_live_…` — not the publishable `pk_` |
|
|
420
|
+
| GitHub | `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_` |
|
|
421
|
+
| Slack | `xoxb-`, `xoxa-`, `xoxp-`, `xoxr-`, `xoxs-` |
|
|
422
|
+
| AWS | access key ids, `AKIA…` and `ASIA…` |
|
|
423
|
+
| JWTs | `eyJ….eyJ….…` |
|
|
424
|
+
| Private keys | a `-----BEGIN … PRIVATE KEY-----` block |
|
|
425
|
+
|
|
426
|
+
Everything else needs two things together: a label right in front of it — `key`, `token`, `secret`,
|
|
427
|
+
`password`, `api`, `auth`, as part of a longer name too (`api_key=`, `"client_secret":`,
|
|
428
|
+
`X-Api-Key:`, a `<dt>API key</dt>` before the `<dd>`) — and a value that looks generated: `Bearer`
|
|
429
|
+
or `Basic` followed by one, or a long hex or base64 run.
|
|
430
|
+
|
|
431
|
+
**What is left alone matters as much.** A forty-character commit hash is not a secret, and neither is
|
|
432
|
+
a UUID — even after the word "key", because an idempotency key is a UUID. Neither is `key:
|
|
433
|
+
MyComponentHeaderTitle`, `const apiKey = process.env.API_KEY`, `sk-fading-circle` (SpinKit's CSS),
|
|
434
|
+
`Bearer YOUR_TOKEN_HERE`, or ordinary sentences about keys and tokens. A generated value is told
|
|
435
|
+
from a written one by measure, not by guess: random characters mix both cases and digits and seldom
|
|
436
|
+
run three lowercase letters together, and names do the opposite. Run over 300,000 lines of Daybook's
|
|
437
|
+
own front end, docs and backend, the rules found one thing — and it was a key.
|
|
438
|
+
|
|
439
|
+
Text painted into a canvas, an image of text, and the inside of another component's shadow root are
|
|
440
|
+
not read. A blur covers those.
|
|
441
|
+
|
|
442
|
+
### What the reporter blurs
|
|
443
|
+
|
|
444
|
+
The composer offers **Blur something** beside *Add another pin*, and it is the same gesture: click an
|
|
445
|
+
element, or drag across an area — a corner of a chart, half a table. What a click would blur is shown
|
|
446
|
+
blurred under the pointer first, every blur stays on the page while the report is written, each is
|
|
447
|
+
listed in the panel with its own remove, and Esc backs out.
|
|
448
|
+
|
|
449
|
+
A blur applies to the screenshot exactly as the reporter saw it, and the element is blurred for the
|
|
450
|
+
frame the way a private one is. In the page snapshot the subtree is withheld as
|
|
451
|
+
`<section data-daybook-blurred>[withheld]</section>`; for an area, every element drawn wholly inside
|
|
452
|
+
it and every piece of text drawn under it. A pin on something blurred is sent without its text.
|
|
453
|
+
|
|
454
|
+
Nothing about a blur goes on the wire but a count: no selector, no text. It holds with `redact: false`.
|
|
455
|
+
|
|
456
|
+
## Offline
|
|
457
|
+
|
|
458
|
+
A report written the moment something breaks is frequently written the moment the network is also
|
|
459
|
+
broken. Failed sends are queued in `localStorage` and retried on the next visit, carrying an
|
|
460
|
+
idempotency key so a retry the server already received returns the original rather than filing a
|
|
461
|
+
duplicate. 4xx responses other than 429 are not retried — a client that retries a rejected body
|
|
462
|
+
forever becomes a denial of service against its own backend.
|
|
463
|
+
|
|
464
|
+
## Without the UI
|
|
465
|
+
|
|
466
|
+
```js
|
|
467
|
+
const pm = init({ … })
|
|
468
|
+
|
|
469
|
+
pm.open() // your own "Report a problem" menu item
|
|
470
|
+
await pm.report('Checkout threw', { // a caught error, no user present
|
|
471
|
+
kind: 'bug',
|
|
472
|
+
context: { orderId: '123' },
|
|
473
|
+
})
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
`report()` takes no screenshot: there is nobody there to consent to a screen share.
|
|
477
|
+
|
|
478
|
+
## The look is set in Daybook, not in code
|
|
479
|
+
|
|
480
|
+
Everything about the widget's appearance lives on the integration, so it is changed on the Feedback
|
|
481
|
+
widget page in Daybook and takes effect on every install of that key without a deploy:
|
|
482
|
+
|
|
483
|
+
| | |
|
|
484
|
+
|---|---|
|
|
485
|
+
| Button style | `pill`, `pill-icon`, `icon`, `text`, `outline` |
|
|
486
|
+
| Button text | Anything up to 24 characters. Defaults to "Feedback" |
|
|
487
|
+
| Colour scheme | `auto` (the default), `light`, `dark` |
|
|
488
|
+
| Corner | Bottom right by default — and `placement` in `init()` overrides it |
|
|
489
|
+
| Accent | Any CSS colour |
|
|
490
|
+
|
|
491
|
+
**Auto is the default and is the one to keep.** The widget is a guest on your page, and your page is
|
|
492
|
+
already light or dark for that reader; following their own setting is almost always right. Pin it
|
|
493
|
+
only when your app is one or the other regardless of the system.
|
|
494
|
+
|
|
495
|
+
The five button styles exist because one button cannot be right for every page. A product with its
|
|
496
|
+
own bold chat bubble does not want a second bold pill beside it; a spare documentation site does not
|
|
497
|
+
want a filled button at all; a dense application usually wants the smallest possible mark. All five
|
|
498
|
+
keep the same hit area in the same corner, so nothing else about the widget changes with the choice.
|
|
499
|
+
|
|
500
|
+
If you are building your own settings screen, `previewLauncher(element, theme)` draws the real
|
|
501
|
+
button — the real stylesheet, in a shadow root — so a preview cannot drift from the thing it
|
|
502
|
+
previews.
|
|
503
|
+
|
|
504
|
+
## Theming, but not styling
|
|
505
|
+
|
|
506
|
+
The widget renders in a shadow root. A host page's `* { }` reset, its `button { all: unset }`, or its
|
|
507
|
+
own stacking context cannot reach in — which matters because the page someone is reporting a problem
|
|
508
|
+
on is exactly the page whose CSS you should not trust.
|
|
509
|
+
|
|
510
|
+
So it is themed from Daybook rather than from your stylesheet: accent colour, corner radius, position
|
|
511
|
+
and launcher label are set on the integration and arrive with the handshake, which means changing
|
|
512
|
+
them needs no redeploy of your site. Anything not on that list is not settable, on purpose.
|
|
513
|
+
|
|
514
|
+
## Limits
|
|
515
|
+
|
|
516
|
+
Two, and they are different things. A **burst limit** of 60 reports a minute per install stops a
|
|
517
|
+
leaked key becoming a write loop. A **period quota** belongs to the whole Daybook project and is what
|
|
518
|
+
runs out at the end of a month; the integrations screen shows how much of it is spent.
|
|
519
|
+
|
|
520
|
+
Attachments go through the API rather than straight to storage, capped per environment — 8 MB by
|
|
521
|
+
default, which is generous for a screenshot.
|