@nagoorkani/session-capture-vue 0.1.0 → 0.1.2
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 +29 -2
- package/dist/index.d.ts +6 -0
- package/dist/index.js +18 -1
- package/dist/page-timing.d.ts +21 -0
- package/dist/page-timing.js +82 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -4,7 +4,9 @@ Session capture and observability for Vue 3 applications. The capture itself is
|
|
|
4
4
|
[`@nagoorkani/session-capture-core`](../core/README.md), shared with the Expo SDK; this
|
|
5
5
|
package is the browser and the Vue of it.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
```bash
|
|
8
|
+
npm install @nagoorkani/session-capture-vue
|
|
9
|
+
```
|
|
8
10
|
|
|
9
11
|
## Setup
|
|
10
12
|
|
|
@@ -21,6 +23,10 @@ createApp(App)
|
|
|
21
23
|
projectId: 'project_…',
|
|
22
24
|
endpoint: 'https://your-ingestion-host',
|
|
23
25
|
appVersion: '1.4.0',
|
|
26
|
+
// Optional: your signed-in user, recorded on every session. Leave out
|
|
27
|
+
// for anonymous visitors; call identify() after a later login.
|
|
28
|
+
appUserId: currentUser?.id,
|
|
29
|
+
appUserEmail: currentUser?.email,
|
|
24
30
|
// Optional: route changes become screen views. Passed in rather than
|
|
25
31
|
// imported, so the SDK never makes vue-router a dependency of an
|
|
26
32
|
// application that routes some other way.
|
|
@@ -43,7 +49,7 @@ would capture every request that process makes for every visitor at once.
|
|
|
43
49
|
import { track, screen, identify, breadcrumb, captureException } from '@nagoorkani/session-capture-vue'
|
|
44
50
|
|
|
45
51
|
track('checkout_started', { cart: 3 })
|
|
46
|
-
identify('user_42', { plan: 'pro' })
|
|
52
|
+
identify('user_42', { email: 'ana@example.com', plan: 'pro' })
|
|
47
53
|
breadcrumb('coupon applied')
|
|
48
54
|
captureException(error, { where: 'checkout' })
|
|
49
55
|
```
|
|
@@ -58,6 +64,27 @@ errors thrown inside components, which Vue catches itself and would otherwise
|
|
|
58
64
|
never reach `window` — the plugin chains `app.config.errorHandler` rather than
|
|
59
65
|
replacing it, so whatever the application already had there still runs.
|
|
60
66
|
|
|
67
|
+
## Performance
|
|
68
|
+
|
|
69
|
+
Page-load timings are captured automatically from what the browser already
|
|
70
|
+
measured — no dependency, nothing to call: `ttfb`, `first_contentful_paint`,
|
|
71
|
+
`dom_content_loaded`, `page_load`, and `largest_contentful_paint`, which is only
|
|
72
|
+
final once the user leaves, so it is sent when the tab is hidden. They appear on
|
|
73
|
+
the session's Performance tab. Only the initial load is timed: a route change
|
|
74
|
+
inside the app is not a navigation to the browser.
|
|
75
|
+
|
|
76
|
+
Anything else, time yourself:
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
import { startMeasure, endMeasure, markAppReady } from '@nagoorkani/session-capture-vue'
|
|
80
|
+
|
|
81
|
+
startMeasure('search')
|
|
82
|
+
await runSearch()
|
|
83
|
+
endMeasure('search') // recorded as "search 412ms"
|
|
84
|
+
|
|
85
|
+
markAppReady() // time from SDK load until your app says it is usable
|
|
86
|
+
```
|
|
87
|
+
|
|
61
88
|
## Sessions
|
|
62
89
|
|
|
63
90
|
**One per tab.** A session lives in `sessionStorage`, so a reload continues it
|
package/dist/index.d.ts
CHANGED
|
@@ -58,6 +58,12 @@ export declare const onError: (listener: (sessionId: string) => void) => () => v
|
|
|
58
58
|
* session the backend had already closed.
|
|
59
59
|
*/
|
|
60
60
|
export declare const keepSessionAlive: () => void | undefined;
|
|
61
|
+
/** Start a named timing; `endMeasure` with the same name records it. */
|
|
62
|
+
export declare const startMeasure: (name: string) => void | undefined;
|
|
63
|
+
/** Finish a named timing and record it on the Performance tab. */
|
|
64
|
+
export declare const endMeasure: (name: string) => void | undefined;
|
|
65
|
+
/** Record time from SDK load until the app says it is usable. */
|
|
66
|
+
export declare const markAppReady: () => void | undefined;
|
|
61
67
|
/** Stop capturing and unwind everything installed on the page. */
|
|
62
68
|
export declare const shutdown: () => void | undefined;
|
|
63
69
|
/** A `vue-router` instance, described by the two members used here. */
|
package/dist/index.js
CHANGED
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
import { addBreadcrumb, CONFIG_DIR, DEFAULT_CONFIG, Dispatcher, fetchRemoteConfig, installErrorHandlers, installNetworkCapture, loadCachedConfig, MemoryStore, safe, safeAsync, saveConfig, SDK_VERSION, SdkCore, SendQueue, } from '@nagoorkani/session-capture-core';
|
|
14
14
|
import { readWebContext } from "./context.js";
|
|
15
15
|
import { installLifecycleListener } from "./lifecycle-browser.js";
|
|
16
|
+
import { installPageTiming } from "./page-timing.js";
|
|
16
17
|
import { loadSession, saveSession } from "./session-store.js";
|
|
17
18
|
import { createBrowserStore } from "./store-browser.js";
|
|
18
19
|
export { SCHEMA_VERSION, DEFAULT_CONFIG, SDK_VERSION } from '@nagoorkani/session-capture-core';
|
|
@@ -146,9 +147,13 @@ export const init = safe((options) => {
|
|
|
146
147
|
persistSession();
|
|
147
148
|
// Not awaited: `init` stays synchronous and the session opens immediately.
|
|
148
149
|
void bootstrapConfig(options).catch(() => { });
|
|
150
|
+
const timing = installPageTiming((name, durationMs) => core?.capture('performance', { name, durationMs }));
|
|
151
|
+
teardown.push(timing.stop);
|
|
149
152
|
teardown.push(installLifecycleListener((state) => {
|
|
150
153
|
core?.onAppStateChange(state);
|
|
151
154
|
if (state === 'background') {
|
|
155
|
+
// Before the flush below, so the final LCP leaves with this batch.
|
|
156
|
+
timing.finish();
|
|
152
157
|
// The last chance to do anything. A hidden tab may never run again —
|
|
153
158
|
// frozen into the back/forward cache, or simply closed — so the
|
|
154
159
|
// session is written down and the queue is drained with `keepalive`,
|
|
@@ -211,7 +216,7 @@ export const screen = safe((name) => {
|
|
|
211
216
|
}, undefined, 'screen');
|
|
212
217
|
/** Attach a known user to this session. The erasure target. */
|
|
213
218
|
export const identify = safe((userId, traits) => {
|
|
214
|
-
core?.
|
|
219
|
+
core?.identify(userId, traits);
|
|
215
220
|
persistSession();
|
|
216
221
|
}, undefined, 'identify');
|
|
217
222
|
/** Send everything held right now. */
|
|
@@ -250,6 +255,18 @@ export const keepSessionAlive = safe(() => {
|
|
|
250
255
|
core?.keepAlive();
|
|
251
256
|
persistSession();
|
|
252
257
|
}, undefined, 'keepSessionAlive');
|
|
258
|
+
/** Start a named timing; `endMeasure` with the same name records it. */
|
|
259
|
+
export const startMeasure = safe((name) => {
|
|
260
|
+
core?.mark(name);
|
|
261
|
+
}, undefined, 'startMeasure');
|
|
262
|
+
/** Finish a named timing and record it on the Performance tab. */
|
|
263
|
+
export const endMeasure = safe((name) => {
|
|
264
|
+
core?.measure(name);
|
|
265
|
+
}, undefined, 'endMeasure');
|
|
266
|
+
/** Record time from SDK load until the app says it is usable. */
|
|
267
|
+
export const markAppReady = safe(() => {
|
|
268
|
+
core?.markReady();
|
|
269
|
+
}, undefined, 'markAppReady');
|
|
253
270
|
/** Stop capturing and unwind everything installed on the page. */
|
|
254
271
|
export const shutdown = safe(() => {
|
|
255
272
|
for (const undo of teardown.splice(0)) {
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Page-load timings the browser has already measured.
|
|
3
|
+
*
|
|
4
|
+
* Free: Navigation Timing and paint entries cost nothing to read and need no
|
|
5
|
+
* dependency, which is why the web SDK has them while Expo, without a native
|
|
6
|
+
* module, has only what the app measures itself (`performance.ts` in core).
|
|
7
|
+
*
|
|
8
|
+
* ponytail: the initial page load only. A client-side route change is not a
|
|
9
|
+
* navigation to the browser, so SPA transitions are not timed; CLS and INP are
|
|
10
|
+
* not reported either, because neither is a duration and the Performance tab
|
|
11
|
+
* reads durations. Add them when the tab can show a score.
|
|
12
|
+
*/
|
|
13
|
+
type Record = (name: string, durationMs: number) => void;
|
|
14
|
+
interface Timing {
|
|
15
|
+
/** Largest Contentful Paint keeps changing until the user interacts or
|
|
16
|
+
* leaves, so it is reported once, when the page is hidden. */
|
|
17
|
+
finish(): void;
|
|
18
|
+
stop(): void;
|
|
19
|
+
}
|
|
20
|
+
export declare function installPageTiming(record: Record): Timing;
|
|
21
|
+
export {};
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Page-load timings the browser has already measured.
|
|
3
|
+
*
|
|
4
|
+
* Free: Navigation Timing and paint entries cost nothing to read and need no
|
|
5
|
+
* dependency, which is why the web SDK has them while Expo, without a native
|
|
6
|
+
* module, has only what the app measures itself (`performance.ts` in core).
|
|
7
|
+
*
|
|
8
|
+
* ponytail: the initial page load only. A client-side route change is not a
|
|
9
|
+
* navigation to the browser, so SPA transitions are not timed; CLS and INP are
|
|
10
|
+
* not reported either, because neither is a duration and the Performance tab
|
|
11
|
+
* reads durations. Add them when the tab can show a score.
|
|
12
|
+
*/
|
|
13
|
+
const NONE = { finish() { }, stop() { } };
|
|
14
|
+
export function installPageTiming(record) {
|
|
15
|
+
const perf = globalThis.performance;
|
|
16
|
+
const win = globalThis;
|
|
17
|
+
if (!perf?.getEntriesByType || typeof win.addEventListener !== 'function')
|
|
18
|
+
return NONE;
|
|
19
|
+
const report = (name, ms) => {
|
|
20
|
+
if (ms !== undefined && ms > 0)
|
|
21
|
+
record(name, Math.round(ms));
|
|
22
|
+
};
|
|
23
|
+
const onLoad = () => {
|
|
24
|
+
// `loadEventEnd` is only set once the load handlers return, hence a tick.
|
|
25
|
+
setTimeout(() => {
|
|
26
|
+
try {
|
|
27
|
+
const nav = perf.getEntriesByType('navigation')[0];
|
|
28
|
+
report('ttfb', nav?.responseStart);
|
|
29
|
+
report('dom_content_loaded', nav?.domContentLoadedEventEnd);
|
|
30
|
+
report('page_load', nav?.loadEventEnd);
|
|
31
|
+
}
|
|
32
|
+
catch {
|
|
33
|
+
// A timing is never worth an exception in someone else's page.
|
|
34
|
+
}
|
|
35
|
+
}, 0);
|
|
36
|
+
};
|
|
37
|
+
if (win.document?.readyState === 'complete')
|
|
38
|
+
onLoad();
|
|
39
|
+
else
|
|
40
|
+
win.addEventListener('load', onLoad, { once: true });
|
|
41
|
+
// Observed rather than read at load: on a light page the first paint lands
|
|
42
|
+
// after the load event, and would be missed by a read there.
|
|
43
|
+
const observe = (type, onEntries) => {
|
|
44
|
+
try {
|
|
45
|
+
if (!PerformanceObserver.supportedEntryTypes?.includes(type))
|
|
46
|
+
return undefined;
|
|
47
|
+
const observer = new PerformanceObserver((list) => onEntries(list.getEntries()));
|
|
48
|
+
observer.observe({ type, buffered: true });
|
|
49
|
+
return observer;
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
};
|
|
55
|
+
let fcpReported = false;
|
|
56
|
+
const paint = observe('paint', (entries) => {
|
|
57
|
+
const fcp = entries.find((e) => e.name === 'first-contentful-paint');
|
|
58
|
+
if (fcp && !fcpReported) {
|
|
59
|
+
fcpReported = true;
|
|
60
|
+
report('first_contentful_paint', fcp.startTime);
|
|
61
|
+
}
|
|
62
|
+
});
|
|
63
|
+
let lcp;
|
|
64
|
+
let largest = observe('largest-contentful-paint', (entries) => {
|
|
65
|
+
lcp = entries.at(-1)?.startTime ?? lcp;
|
|
66
|
+
});
|
|
67
|
+
const stop = () => {
|
|
68
|
+
paint?.disconnect();
|
|
69
|
+
largest?.disconnect();
|
|
70
|
+
largest = undefined;
|
|
71
|
+
win.removeEventListener?.('load', onLoad);
|
|
72
|
+
};
|
|
73
|
+
return {
|
|
74
|
+
finish() {
|
|
75
|
+
if (!largest)
|
|
76
|
+
return;
|
|
77
|
+
report('largest_contentful_paint', lcp);
|
|
78
|
+
stop();
|
|
79
|
+
},
|
|
80
|
+
stop,
|
|
81
|
+
};
|
|
82
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nagoorkani/session-capture-vue",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Session capture and observability for Vue 3 applications",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"type": "module",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"analytics"
|
|
26
26
|
],
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@nagoorkani/session-capture-core": "0.1.
|
|
28
|
+
"@nagoorkani/session-capture-core": "0.1.4"
|
|
29
29
|
},
|
|
30
30
|
"peerDependencies": {
|
|
31
31
|
"vue": ">=3.3"
|