@daybook/analytics 0.0.0-stage → 0.2.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/CHANGELOG.md +33 -0
- package/LICENSE +21 -0
- package/README.md +439 -3
- package/dist/browser.d.ts +1 -0
- package/dist/browser.js +30 -0
- package/dist/client.d.ts +123 -0
- package/dist/client.js +448 -0
- package/dist/context.d.ts +40 -0
- package/dist/context.js +133 -0
- package/dist/daybook.js +1 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +28 -0
- package/dist/log.d.ts +11 -0
- package/dist/log.js +20 -0
- package/dist/react.d.ts +27 -0
- package/dist/react.js +36 -0
- package/dist/storage.d.ts +44 -0
- package/dist/storage.js +102 -0
- package/dist/transport.d.ts +118 -0
- package/dist/transport.js +255 -0
- package/dist/types.d.ts +87 -0
- package/dist/types.js +1 -0
- package/dist/uuid.d.ts +5 -0
- package/dist/uuid.js +19 -0
- package/dist/version.d.ts +11 -0
- package/dist/version.js +11 -0
- package/dist/vue.d.ts +37 -0
- package/dist/vue.js +47 -0
- package/package.json +80 -6
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
/** What a property can hold: anything JSON can carry. A `Date` is sent as ISO 8601 text. */
|
|
2
|
+
export type PropertyValue = string | number | boolean | null | Date | PropertyValue[] | {
|
|
3
|
+
[key: string]: PropertyValue | undefined;
|
|
4
|
+
};
|
|
5
|
+
/** An event's or a person's properties. `undefined` values are left out. */
|
|
6
|
+
export type Properties = Record<string, PropertyValue | undefined>;
|
|
7
|
+
/**
|
|
8
|
+
* Where an event happened. Each one is a typed column in the Analytics hub, so a breakdown by browser
|
|
9
|
+
* or OS reads one small column instead of the event's properties.
|
|
10
|
+
*/
|
|
11
|
+
export interface EventContext {
|
|
12
|
+
app_version?: string;
|
|
13
|
+
os?: string;
|
|
14
|
+
os_version?: string;
|
|
15
|
+
device_type?: string;
|
|
16
|
+
device_model?: string;
|
|
17
|
+
browser?: string;
|
|
18
|
+
locale?: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* One event exactly as it is sent to `/analytics/v1/batch`, which is also what `beforeSend` is given.
|
|
22
|
+
* Field names are the API's.
|
|
23
|
+
*/
|
|
24
|
+
export interface AnalyticsEvent {
|
|
25
|
+
event: string;
|
|
26
|
+
/** A UUID made for this event; a retry carries the same one, so the store keeps it once. */
|
|
27
|
+
event_id: string;
|
|
28
|
+
/** The browser's anonymous id, kept across visits until `reset()`. */
|
|
29
|
+
distinct_id: string;
|
|
30
|
+
/** Who signed in, once `identify()` has been called. */
|
|
31
|
+
user_id?: string;
|
|
32
|
+
/** ISO 8601, from the browser's clock. */
|
|
33
|
+
timestamp: string;
|
|
34
|
+
session_id: string;
|
|
35
|
+
properties: Record<string, unknown>;
|
|
36
|
+
context: EventContext;
|
|
37
|
+
}
|
|
38
|
+
/** Where the SDK keeps the anonymous id, the session, registered properties and the consent choice. */
|
|
39
|
+
export type Persistence = 'localStorage' | 'cookie' | 'memory';
|
|
40
|
+
export interface AnalyticsOptions {
|
|
41
|
+
/** The project's ingest key, `dak_…`, from Analytics → Settings. It is public: it only says which project events are for. */
|
|
42
|
+
key: string;
|
|
43
|
+
/** Where Daybook's API is. Only for a self-hosted Daybook or a proxy of your own. */
|
|
44
|
+
apiUrl?: string;
|
|
45
|
+
/** Your site's own version or build, kept as the `app_version` of every event. */
|
|
46
|
+
appVersion?: string;
|
|
47
|
+
/**
|
|
48
|
+
* Page views without a line of code: one on load and one on every navigation of a single-page app
|
|
49
|
+
* (History API and `#/` routes). On by default. Set `false` to call `page()` yourself — the Vue
|
|
50
|
+
* plugin does that when it is given the router.
|
|
51
|
+
*/
|
|
52
|
+
autoPageviews?: boolean;
|
|
53
|
+
/** A `$pageleave`, with the time the page was open, when a page is left. On by default. */
|
|
54
|
+
pageleave?: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* `localStorage` (the default) keeps the anonymous id per site. `cookie` shares it across
|
|
57
|
+
* subdomains — set `cookieDomain` to `.example.com` so `www.` and `app.` count one visitor. `memory`
|
|
58
|
+
* keeps nothing past the page: every page load is a new visitor.
|
|
59
|
+
*/
|
|
60
|
+
persistence?: Persistence;
|
|
61
|
+
/** With `persistence: 'cookie'`: the domain the cookie is set for, such as `.example.com`. */
|
|
62
|
+
cookieDomain?: string;
|
|
63
|
+
/** Minutes without an event after which the next one starts a new session. 30 by default. */
|
|
64
|
+
sessionTimeoutMinutes?: number;
|
|
65
|
+
/** How long events wait to be sent together, in milliseconds. 2,000 by default. */
|
|
66
|
+
flushIntervalMs?: number;
|
|
67
|
+
/** Events per request, at most 1,000. 50 by default. */
|
|
68
|
+
batchSize?: number;
|
|
69
|
+
/** Properties sent with every event from the start, as `register()` would. */
|
|
70
|
+
properties?: Properties;
|
|
71
|
+
/**
|
|
72
|
+
* Send and store nothing until `optIn()` — for a site that asks for consent first. The anonymous id
|
|
73
|
+
* is not written to storage before then either.
|
|
74
|
+
*/
|
|
75
|
+
optOutByDefault?: boolean;
|
|
76
|
+
/** Send nothing from a browser with Do Not Track or Global Privacy Control on, unless `optIn()` is called. */
|
|
77
|
+
respectDoNotTrack?: boolean;
|
|
78
|
+
/** Leave out browsers whose user agent says they are a crawler. On by default. */
|
|
79
|
+
ignoreBots?: boolean;
|
|
80
|
+
/**
|
|
81
|
+
* Sees every event just before it is queued. Return it (changed or not) to send it, or `null` to
|
|
82
|
+
* drop it — to take a token out of a URL, say.
|
|
83
|
+
*/
|
|
84
|
+
beforeSend?: (event: AnalyticsEvent) => AnalyticsEvent | null | undefined | false;
|
|
85
|
+
/** Log what is sent and why anything is not. */
|
|
86
|
+
debug?: boolean;
|
|
87
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/uuid.d.ts
ADDED
package/dist/uuid.js
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A random (v4) UUID. `crypto.randomUUID` exists only in a secure context, so a page served over
|
|
3
|
+
* plain http — a local dev server on a LAN address — falls back to `getRandomValues`, which does not.
|
|
4
|
+
*/
|
|
5
|
+
export function uuid() {
|
|
6
|
+
const c = globalThis.crypto;
|
|
7
|
+
if (typeof c?.randomUUID === 'function')
|
|
8
|
+
return c.randomUUID();
|
|
9
|
+
const b = new Uint8Array(16);
|
|
10
|
+
if (typeof c?.getRandomValues === 'function')
|
|
11
|
+
c.getRandomValues(b);
|
|
12
|
+
else
|
|
13
|
+
for (let i = 0; i < 16; i++)
|
|
14
|
+
b[i] = Math.floor(Math.random() * 256);
|
|
15
|
+
b[6] = (b[6] & 0x0f) | 0x40;
|
|
16
|
+
b[8] = (b[8] & 0x3f) | 0x80;
|
|
17
|
+
const hex = Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
|
|
18
|
+
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
|
|
19
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This build's own version, sent as `$lib_version` on every event so a project can see which builds
|
|
3
|
+
* of the SDK its pages run. A constant rather than read from package.json at build time, because the
|
|
4
|
+
* npm build is plain tsc; test/version.test.js refuses a build where the two disagree.
|
|
5
|
+
*/
|
|
6
|
+
export declare const SDK_VERSION = "0.2.0";
|
|
7
|
+
/**
|
|
8
|
+
* What the API records as every event's `source`, and one of the names it knows as a Daybook SDK
|
|
9
|
+
* (PM-T-0528): only those may send `$pageview` and `$pageleave`.
|
|
10
|
+
*/
|
|
11
|
+
export declare const SDK_NAME = "js";
|
package/dist/version.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This build's own version, sent as `$lib_version` on every event so a project can see which builds
|
|
3
|
+
* of the SDK its pages run. A constant rather than read from package.json at build time, because the
|
|
4
|
+
* npm build is plain tsc; test/version.test.js refuses a build where the two disagree.
|
|
5
|
+
*/
|
|
6
|
+
export const SDK_VERSION = '0.2.0';
|
|
7
|
+
/**
|
|
8
|
+
* What the API records as every event's `source`, and one of the names it knows as a Daybook SDK
|
|
9
|
+
* (PM-T-0528): only those may send `$pageview` and `$pageleave`.
|
|
10
|
+
*/
|
|
11
|
+
export const SDK_NAME = 'js';
|
package/dist/vue.d.ts
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { type App, type InjectionKey } from 'vue';
|
|
2
|
+
import { DaybookAnalytics } from './index.js';
|
|
3
|
+
import type { AnalyticsOptions } from './types.js';
|
|
4
|
+
export { DaybookAnalytics } from './index.js';
|
|
5
|
+
export type { AnalyticsEvent, AnalyticsOptions, Properties } from './index.js';
|
|
6
|
+
/** As much of Vue Router as page views need, so the package does not depend on it. */
|
|
7
|
+
export interface RouterLike {
|
|
8
|
+
afterEach(guard: (to: unknown, from: unknown, failure?: unknown) => unknown): () => void;
|
|
9
|
+
}
|
|
10
|
+
export interface VueAnalyticsOptions extends AnalyticsOptions {
|
|
11
|
+
/**
|
|
12
|
+
* The app's router. Page views then come from each finished navigation, after the new route's
|
|
13
|
+
* component has rendered, instead of from the History API.
|
|
14
|
+
*/
|
|
15
|
+
router?: RouterLike;
|
|
16
|
+
}
|
|
17
|
+
export declare const AnalyticsKey: InjectionKey<DaybookAnalytics>;
|
|
18
|
+
/**
|
|
19
|
+
* Analytics for a Vue app (PM-R-0062 criterion 6):
|
|
20
|
+
*
|
|
21
|
+
* app.use(createAnalytics({ key: 'dak_…', router }))
|
|
22
|
+
*
|
|
23
|
+
* Then `useAnalytics()` in a component's setup, or `$daybook` in a template.
|
|
24
|
+
*/
|
|
25
|
+
export declare function createAnalytics(options: VueAnalyticsOptions | {
|
|
26
|
+
client: DaybookAnalytics;
|
|
27
|
+
}): {
|
|
28
|
+
client: DaybookAnalytics;
|
|
29
|
+
install(app: App): void;
|
|
30
|
+
};
|
|
31
|
+
/** The app's analytics, in a component's setup. */
|
|
32
|
+
export declare function useAnalytics(): DaybookAnalytics;
|
|
33
|
+
declare module 'vue' {
|
|
34
|
+
interface ComponentCustomProperties {
|
|
35
|
+
$daybook: DaybookAnalytics;
|
|
36
|
+
}
|
|
37
|
+
}
|
package/dist/vue.js
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { inject, nextTick } from 'vue';
|
|
2
|
+
import { DaybookAnalytics, init } from './index.js';
|
|
3
|
+
export { DaybookAnalytics } from './index.js';
|
|
4
|
+
export const AnalyticsKey = Symbol('daybook-analytics');
|
|
5
|
+
/**
|
|
6
|
+
* Analytics for a Vue app (PM-R-0062 criterion 6):
|
|
7
|
+
*
|
|
8
|
+
* app.use(createAnalytics({ key: 'dak_…', router }))
|
|
9
|
+
*
|
|
10
|
+
* Then `useAnalytics()` in a component's setup, or `$daybook` in a template.
|
|
11
|
+
*/
|
|
12
|
+
export function createAnalytics(options) {
|
|
13
|
+
const client = 'client' in options ? options.client : start(options);
|
|
14
|
+
return {
|
|
15
|
+
client,
|
|
16
|
+
install(app) {
|
|
17
|
+
app.provide(AnalyticsKey, client);
|
|
18
|
+
app.config.globalProperties.$daybook = client;
|
|
19
|
+
},
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
function start({ router, ...options }) {
|
|
23
|
+
if (!router)
|
|
24
|
+
return init(options);
|
|
25
|
+
const client = init({ ...options, autoPageviews: false });
|
|
26
|
+
// A failed or cancelled navigation is not a page view, and neither is one that only changed the
|
|
27
|
+
// query or the hash of the same route. nextTick: the route's component and any title it sets are on
|
|
28
|
+
// the page by then.
|
|
29
|
+
let last = null;
|
|
30
|
+
router.afterEach((to, _from, failure) => {
|
|
31
|
+
if (failure)
|
|
32
|
+
return;
|
|
33
|
+
const path = to?.path ?? null;
|
|
34
|
+
if (path !== null && path === last)
|
|
35
|
+
return;
|
|
36
|
+
last = path;
|
|
37
|
+
void nextTick(() => client.page());
|
|
38
|
+
});
|
|
39
|
+
return client;
|
|
40
|
+
}
|
|
41
|
+
/** The app's analytics, in a component's setup. */
|
|
42
|
+
export function useAnalytics() {
|
|
43
|
+
const client = inject(AnalyticsKey, null);
|
|
44
|
+
if (!client)
|
|
45
|
+
throw new Error('@daybook/analytics/vue: useAnalytics needs app.use(createAnalytics({ key })) first.');
|
|
46
|
+
return client;
|
|
47
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,80 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@daybook/analytics",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@daybook/analytics",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Product analytics for the web: page views, sessions, attribution and your own events, sent to Daybook's Analytics hub. Plain JS, React and Vue.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
|
+
"unpkg": "dist/daybook.js",
|
|
9
|
+
"jsdelivr": "dist/daybook.js",
|
|
10
|
+
"files": [
|
|
11
|
+
"dist",
|
|
12
|
+
"README.md",
|
|
13
|
+
"CHANGELOG.md"
|
|
14
|
+
],
|
|
15
|
+
"scripts": {
|
|
16
|
+
"build": "tsc -p tsconfig.json && npm run bundle",
|
|
17
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
18
|
+
"test": "node --test test/*.test.js",
|
|
19
|
+
"bundle": "esbuild src/browser.ts --bundle --format=iife --minify --target=es2019 --outfile=dist/daybook.js",
|
|
20
|
+
"prepublishOnly": "npm run build && npm test",
|
|
21
|
+
"release": "node ../../devops/publish-sdk.mjs analytics"
|
|
22
|
+
},
|
|
23
|
+
"peerDependencies": {
|
|
24
|
+
"react": ">=17",
|
|
25
|
+
"vue": ">=3.3"
|
|
26
|
+
},
|
|
27
|
+
"peerDependenciesMeta": {
|
|
28
|
+
"react": {
|
|
29
|
+
"optional": true
|
|
30
|
+
},
|
|
31
|
+
"vue": {
|
|
32
|
+
"optional": true
|
|
33
|
+
}
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@types/react": "^19.3.0",
|
|
37
|
+
"esbuild": "^0.28.2",
|
|
38
|
+
"react": "^19.3.1",
|
|
39
|
+
"react-dom": "^19.3.1",
|
|
40
|
+
"typescript": "^5.7.2",
|
|
41
|
+
"vue": "^3.5.13"
|
|
42
|
+
},
|
|
43
|
+
"allowScripts": {
|
|
44
|
+
"esbuild@0.28.2": true
|
|
45
|
+
},
|
|
46
|
+
"exports": {
|
|
47
|
+
".": {
|
|
48
|
+
"types": "./dist/index.d.ts",
|
|
49
|
+
"import": "./dist/index.js"
|
|
50
|
+
},
|
|
51
|
+
"./react": {
|
|
52
|
+
"types": "./dist/react.d.ts",
|
|
53
|
+
"import": "./dist/react.js"
|
|
54
|
+
},
|
|
55
|
+
"./vue": {
|
|
56
|
+
"types": "./dist/vue.d.ts",
|
|
57
|
+
"import": "./dist/vue.js"
|
|
58
|
+
},
|
|
59
|
+
"./browser": "./dist/daybook.js"
|
|
60
|
+
},
|
|
61
|
+
"sideEffects": [
|
|
62
|
+
"./dist/browser.js",
|
|
63
|
+
"./dist/daybook.js"
|
|
64
|
+
],
|
|
65
|
+
"license": "MIT",
|
|
66
|
+
"publishConfig": {
|
|
67
|
+
"access": "public"
|
|
68
|
+
},
|
|
69
|
+
"homepage": "https://daybook.team",
|
|
70
|
+
"keywords": [
|
|
71
|
+
"analytics",
|
|
72
|
+
"product-analytics",
|
|
73
|
+
"events",
|
|
74
|
+
"pageviews",
|
|
75
|
+
"react",
|
|
76
|
+
"vue",
|
|
77
|
+
"nextjs",
|
|
78
|
+
"nuxt"
|
|
79
|
+
]
|
|
80
|
+
}
|