@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/CHANGELOG.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Every published version of `@daybook/analytics`. `npm run release` (`devops/publish-sdk.sh analytics`) refuses a version
|
|
4
|
+
that has no entry here: a release nobody wrote down is a release nobody hears of.
|
|
5
|
+
|
|
6
|
+
## 0.2.0
|
|
7
|
+
|
|
8
|
+
Events at their true time, first touch on the person, and sessions as every Daybook SDK keeps them.
|
|
9
|
+
|
|
10
|
+
- Every batch carries `sent_at`, stamped as the request leaves — each retry and each beacon anew — so
|
|
11
|
+
Daybook places an event at the time it happened when the visitor's clock is wrong or the event waited
|
|
12
|
+
offline (PM-R-0068).
|
|
13
|
+
- `setPersonPropertiesOnce`: a person property written only where the person has none yet (PM-R-0067).
|
|
14
|
+
- Where the browser first came from (`$initial_referrer`, `$initial_referring_domain`, `$initial_utm_*`) is
|
|
15
|
+
set once on the person by itself, with the browser's first event, as `$set_once`.
|
|
16
|
+
- Sessions (PM-R-0069): a session also ends after 24 hours of steady use, and each opens with
|
|
17
|
+
`$session_start`, carrying the referrer and campaign it began from. Still shared by every tab, still new
|
|
18
|
+
after 30 minutes idle and on `reset()`.
|
|
19
|
+
|
|
20
|
+
## 0.1.0
|
|
21
|
+
|
|
22
|
+
First release (PM-R-0062).
|
|
23
|
+
|
|
24
|
+
- `init` / `new DaybookAnalytics({ key })`; `track`, `page`, `identify`, `reset`, `setPersonProperties`,
|
|
25
|
+
`register` / `unregister`, `optIn` / `optOut`, `flush`.
|
|
26
|
+
- Page views on load and on every navigation of a single-page app, with `$pageleave` and time on page;
|
|
27
|
+
sessions after 30 minutes idle; UTM and referrer, with the browser's first ones kept as `$initial_*`.
|
|
28
|
+
- Batched delivery as CORS-simple requests; retry with backoff; `sendBeacon` when the page is hidden; a
|
|
29
|
+
queue in `sessionStorage` that survives a reload.
|
|
30
|
+
- Consent: `optOutByDefault`, `respectDoNotTrack`, `beforeSend`; crawlers left out.
|
|
31
|
+
- `@daybook/analytics/react` (`DaybookProvider`, `useAnalytics`) and `@daybook/analytics/vue`
|
|
32
|
+
(`createAnalytics`, `useAnalytics`, Vue Router page views).
|
|
33
|
+
- The script-tag build, `dist/daybook.js`, served at `https://daybook.team/sdk/v1/daybook.js`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Daybook
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,439 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# `@daybook/analytics`
|
|
2
|
+
|
|
3
|
+
Product analytics for the web, sent to Daybook's Analytics hub. Page views, sessions, where visitors came
|
|
4
|
+
from, their browser and device — without a line of code — and your own events with `track`. A visitor's
|
|
5
|
+
events before and after they sign in count as one person.
|
|
6
|
+
|
|
7
|
+
Plain JavaScript, React (Next.js too) and Vue (Nuxt too). No dependencies; about 7 KB gzipped as a
|
|
8
|
+
script tag. Safe to import in server-rendered code: on the server every call does nothing.
|
|
9
|
+
|
|
10
|
+
- [Get a key](#get-a-key)
|
|
11
|
+
- [Install](#install): [script tag](#script-tag) · [npm](#npm) · [React](#react) · [Next.js](#nextjs) · [Vue](#vue) · [Nuxt](#nuxt)
|
|
12
|
+
- [Events](#events) · [Page views](#page-views) · [Users: identify and reset](#users-identify-and-reset) · [Properties on every event](#properties-on-every-event)
|
|
13
|
+
- [Consent and privacy](#consent-and-privacy) · [Delivery](#delivery) · [Options](#options) · [Methods](#methods)
|
|
14
|
+
- [What is sent](#what-is-sent) · [Troubleshooting](#troubleshooting)
|
|
15
|
+
|
|
16
|
+
## Get a key
|
|
17
|
+
|
|
18
|
+
In Daybook, open the project's **Analytics → Settings** and issue an ingest key for the build that will send
|
|
19
|
+
events — one for production, one for staging. Copy it when it is shown: only its first characters are kept.
|
|
20
|
+
|
|
21
|
+
The key starts with `dak_`. It is public by design, like any analytics key: it only says which project
|
|
22
|
+
events are for, so it is fine in a page's source. Revoking it in Settings stops it at once.
|
|
23
|
+
|
|
24
|
+
The same page shows the snippets below with your key filled in.
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
### Script tag
|
|
29
|
+
|
|
30
|
+
No build step. Put it in the `<head>`, with your key:
|
|
31
|
+
|
|
32
|
+
```html
|
|
33
|
+
<script src="https://daybook.team/sdk/v1/daybook.js" data-key="dak_…"></script>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
That is all page views need. Your own events, anywhere after it:
|
|
37
|
+
|
|
38
|
+
```html
|
|
39
|
+
<script>
|
|
40
|
+
daybook.track('signed_up', { plan: 'pro' })
|
|
41
|
+
</script>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The script starts by itself from its `data-` attributes and is `window.daybook`. Every [option](#options)
|
|
45
|
+
has one: `data-api-url`, `data-app-version`, `data-pageviews="false"`, `data-pageleave="false"`,
|
|
46
|
+
`data-persistence="cookie"`, `data-cookie-domain=".example.com"`, `data-opt-out-by-default`,
|
|
47
|
+
`data-respect-dnt`, `data-debug`.
|
|
48
|
+
|
|
49
|
+
**Loading it async.** To keep it off the critical path, load it `async` and put this stub before it. Calls
|
|
50
|
+
made before the script arrives are queued on the stub and played back in order:
|
|
51
|
+
|
|
52
|
+
```html
|
|
53
|
+
<script>
|
|
54
|
+
window.daybook = window.daybook || { q: [] };
|
|
55
|
+
['track', 'page', 'identify', 'reset', 'register', 'unregister', 'setPersonProperties', 'optIn', 'optOut']
|
|
56
|
+
.forEach(function (m) { daybook[m] = daybook[m] || function () { daybook.q.push([m, [].slice.call(arguments)]) } })
|
|
57
|
+
</script>
|
|
58
|
+
<script async src="https://daybook.team/sdk/v1/daybook.js" data-key="dak_…"></script>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Without `data-key`, start it yourself: `DaybookAnalytics.init({ key: 'dak_…', … })`, which also sets
|
|
62
|
+
`window.daybook`.
|
|
63
|
+
|
|
64
|
+
**A pinned version.** `daybook.team/sdk/v1/daybook.js` is always the newest build that speaks the v1 API.
|
|
65
|
+
To pin one, load it from npm through a public CDN: `https://cdn.jsdelivr.net/npm/@daybook/analytics@0.2.0`
|
|
66
|
+
or `https://unpkg.com/@daybook/analytics@0.2.0` serve the same file.
|
|
67
|
+
|
|
68
|
+
### npm
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
npm install @daybook/analytics
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { init } from '@daybook/analytics'
|
|
76
|
+
|
|
77
|
+
const analytics = init({ key: 'dak_…' })
|
|
78
|
+
|
|
79
|
+
analytics.track('signed_up', { plan: 'pro' })
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`init` starts one instance for the site and returns it on every later call, so it is safe to call from
|
|
83
|
+
wherever is convenient. Anywhere else, `getAnalytics()` returns it. For a second project on the same
|
|
84
|
+
page, `new DaybookAnalytics({ key })` makes an instance of its own.
|
|
85
|
+
|
|
86
|
+
### React
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
import { DaybookProvider } from '@daybook/analytics/react'
|
|
90
|
+
|
|
91
|
+
root.render(
|
|
92
|
+
<DaybookProvider options={{ key: 'dak_…' }}>
|
|
93
|
+
<App />
|
|
94
|
+
</DaybookProvider>,
|
|
95
|
+
)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
99
|
+
import { useAnalytics } from '@daybook/analytics/react'
|
|
100
|
+
|
|
101
|
+
function UpgradeButton() {
|
|
102
|
+
const analytics = useAnalytics()
|
|
103
|
+
return <button onClick={() => analytics.track('upgrade_clicked', { from: 'header' })}>Upgrade</button>
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The provider starts analytics once, however often it renders (StrictMode included). Page views follow the
|
|
108
|
+
History API, so React Router, TanStack Router and the rest need nothing more. To use an instance you made
|
|
109
|
+
yourself: `<DaybookProvider client={analytics}>`.
|
|
110
|
+
|
|
111
|
+
### Next.js
|
|
112
|
+
|
|
113
|
+
App Router: the provider is a client component already (`'use client'` is in the package), so it can go
|
|
114
|
+
straight into the root layout:
|
|
115
|
+
|
|
116
|
+
```tsx
|
|
117
|
+
// app/layout.tsx
|
|
118
|
+
import { DaybookProvider } from '@daybook/analytics/react'
|
|
119
|
+
|
|
120
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
121
|
+
return (
|
|
122
|
+
<html lang="en">
|
|
123
|
+
<body>
|
|
124
|
+
<DaybookProvider options={{ key: process.env.NEXT_PUBLIC_DAYBOOK_KEY! }}>
|
|
125
|
+
{children}
|
|
126
|
+
</DaybookProvider>
|
|
127
|
+
</body>
|
|
128
|
+
</html>
|
|
129
|
+
)
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`useAnalytics()` works in any client component (`'use client'`). In server components, route handlers and
|
|
134
|
+
server actions there is no visitor: track from the client, or send events to the
|
|
135
|
+
[ingest API](#what-is-sent) from your server.
|
|
136
|
+
|
|
137
|
+
Pages Router: wrap `<Component {...pageProps} />` in `pages/_app.tsx` the same way.
|
|
138
|
+
|
|
139
|
+
### Vue
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
// main.ts
|
|
143
|
+
import { createApp } from 'vue'
|
|
144
|
+
import { createAnalytics } from '@daybook/analytics/vue'
|
|
145
|
+
import { router } from './router'
|
|
146
|
+
import App from './App.vue'
|
|
147
|
+
|
|
148
|
+
const app = createApp(App)
|
|
149
|
+
app.use(router)
|
|
150
|
+
app.use(createAnalytics({ key: 'dak_…', router }))
|
|
151
|
+
app.mount('#app')
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
```vue
|
|
155
|
+
<script setup lang="ts">
|
|
156
|
+
import { useAnalytics } from '@daybook/analytics/vue'
|
|
157
|
+
|
|
158
|
+
const analytics = useAnalytics()
|
|
159
|
+
</script>
|
|
160
|
+
|
|
161
|
+
<template>
|
|
162
|
+
<button @click="analytics.track('upgrade_clicked')">Upgrade</button>
|
|
163
|
+
<!-- or, without the import: $daybook.track('upgrade_clicked') -->
|
|
164
|
+
</template>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
With `router`, a page view is sent after each finished navigation to a new path, once the new route has
|
|
168
|
+
rendered — a navigation a guard cancels, or one that only changes the query, is not a page. Without it,
|
|
169
|
+
page views follow the History API like everywhere else.
|
|
170
|
+
|
|
171
|
+
### Nuxt
|
|
172
|
+
|
|
173
|
+
A client-only plugin, with the key in runtime config:
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
// plugins/daybook.client.ts
|
|
177
|
+
import { createAnalytics } from '@daybook/analytics/vue'
|
|
178
|
+
|
|
179
|
+
export default defineNuxtPlugin((nuxtApp) => {
|
|
180
|
+
const { daybookKey } = useRuntimeConfig().public
|
|
181
|
+
nuxtApp.vueApp.use(createAnalytics({ key: daybookKey as string, router: useRouter() }))
|
|
182
|
+
})
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
// nuxt.config.ts
|
|
187
|
+
export default defineNuxtConfig({
|
|
188
|
+
runtimeConfig: { public: { daybookKey: '' } }, // set NUXT_PUBLIC_DAYBOOK_KEY
|
|
189
|
+
})
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## Events
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
analytics.track('checkout_completed', {
|
|
196
|
+
plan: 'pro',
|
|
197
|
+
seats: 3,
|
|
198
|
+
total: 49.0,
|
|
199
|
+
coupon: null,
|
|
200
|
+
renews_at: new Date('2027-01-01'),
|
|
201
|
+
})
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
- **Names** are what someone will pick from a list in a chart: an object and a past-tense verb in
|
|
205
|
+
`snake_case` (`project_created`, `invite_sent`). Keep them few and stable, and put the variety in
|
|
206
|
+
properties: `button_clicked { button: 'upgrade' }`, not one event per button. Names starting with `$` are
|
|
207
|
+
Daybook's own and are refused.
|
|
208
|
+
- **Properties** are strings, numbers, booleans, `null`, dates (sent as ISO 8601), lists and objects.
|
|
209
|
+
A number is filtered and summed as a number, so send `49`, not `'49'`. At most 255 per event and 32 KB.
|
|
210
|
+
- In Daybook, **Analytics → Catalog** lists every event and property the project has sent, with a place to
|
|
211
|
+
describe each one.
|
|
212
|
+
|
|
213
|
+
## Page views
|
|
214
|
+
|
|
215
|
+
On by default: a `$pageview` on load, and one on every navigation of a single-page app (`pushState`,
|
|
216
|
+
`replaceState`, the back button, and `#/` routes). A change of the query string alone is not a new page.
|
|
217
|
+
Each one carries the URL, path, title, referrer, campaign parameters and screen size.
|
|
218
|
+
|
|
219
|
+
When a page is left — a navigation inside the app, or the tab closing — a `$pageleave` says how long it
|
|
220
|
+
was open (`$duration_ms`).
|
|
221
|
+
|
|
222
|
+
To send them yourself instead — after your router has rendered, say:
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
const analytics = init({ key: 'dak_…', autoPageviews: false })
|
|
226
|
+
// on each route change:
|
|
227
|
+
analytics.page()
|
|
228
|
+
analytics.page({ section: 'docs' }) // with properties of your own
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## Sessions
|
|
232
|
+
|
|
233
|
+
A session is one visit: it starts with the first event, and a new one starts after 30 minutes without an
|
|
234
|
+
event (`sessionTimeoutMinutes`), after 24 hours however busy, and on `reset()`. Every tab of the site shares
|
|
235
|
+
the same session. Each one opens with `$session_start`, which carries the page it began on, the referrer
|
|
236
|
+
and the campaign, so Daybook can count sessions, measure how long they last and break them down by entry
|
|
237
|
+
page and source. A session ends at its last event: nothing waits for the tab to close.
|
|
238
|
+
|
|
239
|
+
## Users: identify and reset
|
|
240
|
+
|
|
241
|
+
Every browser gets an anonymous id on its first visit. When the visitor signs in, say who they are:
|
|
242
|
+
|
|
243
|
+
```ts
|
|
244
|
+
analytics.identify(user.id, { email: user.email, plan: user.plan })
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
From then on their events carry the user id, and **everything this browser sent before** counts as theirs
|
|
248
|
+
too — nothing is sent again, Daybook links the two ids. Call it after sign-in and on every page load while
|
|
249
|
+
they are signed in; a repeat costs nothing.
|
|
250
|
+
|
|
251
|
+
When they sign out:
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
analytics.reset()
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
That starts a new anonymous id and session and forgets registered properties, so whoever uses the browser
|
|
258
|
+
next is somebody new. Daybook joins one anonymous id to one user only, so another user signing in on the
|
|
259
|
+
same browser without a `reset()` in between gets a fresh anonymous id automatically.
|
|
260
|
+
|
|
261
|
+
**Person properties** describe the person rather than one event, and filters and breakdowns can use them:
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
analytics.setPersonProperties({ plan: 'team', company: 'Acme' })
|
|
265
|
+
analytics.setPersonProperties({}, ['trial_ends_at']) // unset
|
|
266
|
+
analytics.setPersonPropertiesOnce({ first_plan: 'free', signed_up_at: new Date() })
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
`setPersonPropertiesOnce` writes a property only where the person has no value for it yet — under this
|
|
270
|
+
browser's ids or any other they signed in with — so the first value stays; a later `setPersonProperties`
|
|
271
|
+
still changes it. Properties set before sign-in belong to the person after `identify`.
|
|
272
|
+
|
|
273
|
+
Where the browser first came from — `$initial_referrer`, `$initial_referring_domain` and `$initial_utm_*` —
|
|
274
|
+
is set once on the person by itself, with the browser's first event, so a signup weeks later can be broken
|
|
275
|
+
down by the campaign that first brought the visitor.
|
|
276
|
+
|
|
277
|
+
Use the same user id everywhere you identify the person — the web app, the mobile app, your server — and
|
|
278
|
+
their events from all of them are one person's.
|
|
279
|
+
|
|
280
|
+
## Properties on every event
|
|
281
|
+
|
|
282
|
+
```ts
|
|
283
|
+
analytics.register({ app_section: 'admin', experiment: 'new-pricing-b' })
|
|
284
|
+
analytics.unregister('experiment')
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Registered properties are kept across visits until `reset()`. Options can set some from the start:
|
|
288
|
+
`init({ key, properties: { site: 'docs' } })`.
|
|
289
|
+
|
|
290
|
+
## Consent and privacy
|
|
291
|
+
|
|
292
|
+
| You want | Do |
|
|
293
|
+
|---|---|
|
|
294
|
+
| Nothing sent or stored until the visitor agrees | `optOutByDefault: true`, then `analytics.optIn()` from your consent banner |
|
|
295
|
+
| The visitor declined | `analytics.optOut()` — remembered on their next visit |
|
|
296
|
+
| To honour Do Not Track and Global Privacy Control | `respectDoNotTrack: true` (an explicit `optIn()` still wins) |
|
|
297
|
+
| To keep something out of what is sent | `beforeSend` (below) |
|
|
298
|
+
|
|
299
|
+
With `optOutByDefault`, nothing is written to the browser either — not even the anonymous id — until
|
|
300
|
+
`optIn()`, which then counts the page the visitor is on. After `optOut()` only the choice itself is kept.
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
init({
|
|
304
|
+
key: 'dak_…',
|
|
305
|
+
beforeSend(event) {
|
|
306
|
+
// Take a reset token out of the URL, and drop internal traffic.
|
|
307
|
+
event.properties.$url = String(event.properties.$url).replace(/token=[^&]+/, 'token=…')
|
|
308
|
+
if (event.properties.$host === 'admin.example.com') return null
|
|
309
|
+
return event
|
|
310
|
+
},
|
|
311
|
+
})
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
What the SDK keeps in the browser:
|
|
315
|
+
|
|
316
|
+
- `localStorage` → `dbk_<first letters of the key>`: the anonymous id, the user id after `identify`, the
|
|
317
|
+
session, registered properties, where the browser first came from, and the consent choice. With
|
|
318
|
+
`persistence: 'cookie'` this is a first-party cookie of the same name instead (set `cookieDomain:
|
|
319
|
+
'.example.com'` so `www.` and `app.` share one visitor); with `persistence: 'memory'`, nothing.
|
|
320
|
+
- `sessionStorage` → `dbk_<…>_queue`: events not yet sent, so a reload or a dropped connection loses none.
|
|
321
|
+
|
|
322
|
+
Requests to Daybook carry no cookies and no credentials. Daybook keeps the visitor's country from the
|
|
323
|
+
request and never their IP address.
|
|
324
|
+
|
|
325
|
+
## Delivery
|
|
326
|
+
|
|
327
|
+
Events wait about two seconds (`flushIntervalMs`) and go together, up to 50 a request (`batchSize`).
|
|
328
|
+
|
|
329
|
+
- **Offline, a server error, a 429:** the same batch is tried again — 1 s, 2 s, 4 s, up to five minutes, and
|
|
330
|
+
at once when the browser is back online — with the same event ids, so Daybook stores each event once.
|
|
331
|
+
- **Reload:** what was not sent is still in the tab's `sessionStorage` and goes on the next page.
|
|
332
|
+
- **Leaving the page:** when the page is hidden, what is waiting is handed to `navigator.sendBeacon`, which
|
|
333
|
+
the browser delivers after the page is gone.
|
|
334
|
+
- **Refused:** an event Daybook refuses (a `$` name, too many properties…) is named in a console warning,
|
|
335
|
+
and the rest of its batch is kept. A refused key stops the page sending.
|
|
336
|
+
- **A wrong clock:** every request says when it left (`sent_at`, by the visitor's clock), and Daybook moves
|
|
337
|
+
each event by how far that is from when the request arrived. An event from a computer whose clock is
|
|
338
|
+
two hours slow, or one that waited offline all afternoon, is still placed at the time it happened.
|
|
339
|
+
|
|
340
|
+
`await analytics.flush()` sends everything now — before a redirect to another site, for example.
|
|
341
|
+
|
|
342
|
+
## Options
|
|
343
|
+
|
|
344
|
+
| Option | Default | |
|
|
345
|
+
|---|---|---|
|
|
346
|
+
| `key` | — | **Required.** The ingest key, `dak_…`. |
|
|
347
|
+
| `apiUrl` | `https://api.daybook.team` | A self-hosted Daybook, or a proxy of your own (see [Troubleshooting](#troubleshooting)). |
|
|
348
|
+
| `appVersion` | — | Your site's version or build, kept as the event's `app_version`. |
|
|
349
|
+
| `autoPageviews` | `true` | Page views on load and on every navigation. `false` to call `page()` yourself. |
|
|
350
|
+
| `pageleave` | `true` | A `$pageleave` with the time on the page. |
|
|
351
|
+
| `persistence` | `'localStorage'` | `'cookie'` to share the visitor across subdomains, `'memory'` to keep nothing. |
|
|
352
|
+
| `cookieDomain` | — | With cookies: `.example.com`. |
|
|
353
|
+
| `sessionTimeoutMinutes` | `30` | Idle minutes after which the next event starts a new session; a session also ends after 24 hours. |
|
|
354
|
+
| `flushIntervalMs` | `2000` | How long events wait to go together. |
|
|
355
|
+
| `batchSize` | `50` | Events per request, at most 1,000. |
|
|
356
|
+
| `properties` | — | Registered from the start, as `register()`. |
|
|
357
|
+
| `optOutByDefault` | `false` | Send and store nothing until `optIn()`. |
|
|
358
|
+
| `respectDoNotTrack` | `false` | Send nothing when the browser asks not to be tracked. |
|
|
359
|
+
| `ignoreBots` | `true` | Send nothing from crawlers and link previews. |
|
|
360
|
+
| `beforeSend` | — | `(event) => event \| null`: change or drop any event. |
|
|
361
|
+
| `debug` | `false` | Log every event queued and every request. |
|
|
362
|
+
|
|
363
|
+
## Methods
|
|
364
|
+
|
|
365
|
+
| | |
|
|
366
|
+
|---|---|
|
|
367
|
+
| `track(event, properties?)` | An event. |
|
|
368
|
+
| `page(properties?)` | A page view, when `autoPageviews` is off or for a page of your own. |
|
|
369
|
+
| `identify(userId, properties?)` | The visitor signed in. |
|
|
370
|
+
| `reset()` | The visitor signed out. |
|
|
371
|
+
| `setPersonProperties(set, unset?)` | Properties of the person. |
|
|
372
|
+
| `setPersonPropertiesOnce(properties)` | Properties of the person, only where they have none yet. |
|
|
373
|
+
| `register(properties)` / `unregister(name)` | Properties on every event. |
|
|
374
|
+
| `optIn()` / `optOut()` | The visitor's consent. `optedOut` says where it stands. |
|
|
375
|
+
| `flush()` | Send what is waiting now; resolves when it is sent or Daybook cannot be reached. |
|
|
376
|
+
| `distinctId`, `userId`, `sessionId` | Who and which session events are sent as. |
|
|
377
|
+
| `destroy()` | Stop listening and sending (tests, hot reload). |
|
|
378
|
+
|
|
379
|
+
## What is sent
|
|
380
|
+
|
|
381
|
+
Each event, as `POST https://api.daybook.team/analytics/v1/batch?key=dak_…&sdk=js` with a `text/plain` JSON
|
|
382
|
+
body, so the browser sends it without a CORS preflight:
|
|
383
|
+
|
|
384
|
+
```json
|
|
385
|
+
{
|
|
386
|
+
"sent_at": "2026-10-23T10:15:02.120Z",
|
|
387
|
+
"events": [{
|
|
388
|
+
"event": "signed_up",
|
|
389
|
+
"event_id": "0b8f2c4e-…",
|
|
390
|
+
"distinct_id": "5d1c…",
|
|
391
|
+
"user_id": "user-42",
|
|
392
|
+
"timestamp": "2026-10-23T10:15:00.000Z",
|
|
393
|
+
"session_id": "a71e…",
|
|
394
|
+
"properties": { "plan": "pro", "$url": "https://example.com/signup", "$path": "/signup", "…": "…" },
|
|
395
|
+
"context": { "browser": "Chrome", "os": "macOS", "os_version": "10.15.7", "device_type": "desktop", "locale": "en-GB" }
|
|
396
|
+
}]
|
|
397
|
+
}
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Properties the SDK adds, all starting with `$`:
|
|
401
|
+
|
|
402
|
+
| On | Properties |
|
|
403
|
+
|---|---|
|
|
404
|
+
| every event | `$url`, `$path`, `$host`, `$browser_version`, `$lib_version`, and where the browser first came from: `$initial_referrer`, `$initial_referring_domain`, `$initial_utm_source`, `$initial_utm_medium`, `$initial_utm_campaign`, `$initial_utm_term`, `$initial_utm_content`, `$initial_gclid`, `$initial_fbclid` |
|
|
405
|
+
| `$pageview` | `$title`, `$referrer`, `$referring_domain` (`$direct` for none), `$utm_source` … `$utm_content`, `$gclid`, `$fbclid`, `$screen_width`, `$screen_height`, `$viewport_width`, `$viewport_height` |
|
|
406
|
+
| `$pageleave` | `$duration_ms` |
|
|
407
|
+
| `$session_start` | a session's first event: `$referrer`, `$referring_domain` (`$direct` for none), `$utm_source` … `$utm_content` |
|
|
408
|
+
| the browser's first event | `$set_once`: the `$initial_*` values, which Daybook sets once on the person and keeps off the event |
|
|
409
|
+
|
|
410
|
+
The `context` fields are columns of their own in Daybook — `browser`, `os`, `os_version`, `device_type`,
|
|
411
|
+
`locale`, `app_version` — so a breakdown by them is fast. `country` is added by Daybook from the request.
|
|
412
|
+
|
|
413
|
+
`identify` goes to `/analytics/v1/identify` and person properties to `/analytics/v1/people`. A server can
|
|
414
|
+
call the same three endpoints with the key in an `X-Daybook-Key` header.
|
|
415
|
+
|
|
416
|
+
## Troubleshooting
|
|
417
|
+
|
|
418
|
+
**Nothing on the Events page.** Turn on `debug: true` (or `data-debug`) and look at the console: every
|
|
419
|
+
event queued and every answer is logged. Then check **Analytics → Settings → Data health**, which shows the
|
|
420
|
+
last event received and anything refused, by reason.
|
|
421
|
+
|
|
422
|
+
**A warning names a refused event.** The reason says why: `reserved_event` for a `$` name,
|
|
423
|
+
`too_many_properties`, `properties_too_large`, `invalid_event` for a name over 200 characters.
|
|
424
|
+
|
|
425
|
+
**`the ingest key was refused`.** The key is wrong or revoked. Issue a new one in Settings.
|
|
426
|
+
|
|
427
|
+
**`identify was refused`.** That anonymous id already belongs to another user — two users signed in on
|
|
428
|
+
one browser without `reset()` between them, in two tabs at once. Call `reset()` on sign-out.
|
|
429
|
+
|
|
430
|
+
**Ad blockers.** The script is `daybook.js`, not `analytics.js`, so blockers that drop analytics scripts by
|
|
431
|
+
name pass it; some also block requests to analytics services. For the most complete numbers, install from
|
|
432
|
+
npm (bundled code has no script URL to block) and send through a path on your own domain that forwards to
|
|
433
|
+
`https://api.daybook.team/analytics/v1/`, then set `apiUrl` to your domain.
|
|
434
|
+
|
|
435
|
+
**Content Security Policy.** Allow `connect-src https://api.daybook.team` and, for the script tag,
|
|
436
|
+
`script-src https://daybook.team`.
|
|
437
|
+
|
|
438
|
+
**Local development.** Use a Development key so test traffic stays apart, and with a local Daybook point
|
|
439
|
+
`apiUrl` at it (`http://localhost:5099`).
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/browser.js
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { DaybookAnalytics, getAnalytics, init as start, SDK_VERSION } from './index.js';
|
|
2
|
+
const w = globalThis;
|
|
3
|
+
const script = typeof document !== 'undefined' ? document.currentScript : null;
|
|
4
|
+
function init(options) {
|
|
5
|
+
const stub = w.daybook;
|
|
6
|
+
const instance = start(options);
|
|
7
|
+
w.daybook = instance;
|
|
8
|
+
for (const [method, args] of Array.isArray(stub?.q) ? stub.q : []) {
|
|
9
|
+
const fn = instance[method];
|
|
10
|
+
if (typeof fn === 'function')
|
|
11
|
+
fn.apply(instance, args);
|
|
12
|
+
}
|
|
13
|
+
return instance;
|
|
14
|
+
}
|
|
15
|
+
w.DaybookAnalytics = { init, getAnalytics, DaybookAnalytics, version: SDK_VERSION };
|
|
16
|
+
const data = script?.dataset;
|
|
17
|
+
if (data?.key) {
|
|
18
|
+
init({
|
|
19
|
+
key: data.key,
|
|
20
|
+
apiUrl: data.apiUrl,
|
|
21
|
+
appVersion: data.appVersion,
|
|
22
|
+
autoPageviews: data.pageviews !== 'false',
|
|
23
|
+
pageleave: data.pageleave !== 'false',
|
|
24
|
+
persistence: data.persistence,
|
|
25
|
+
cookieDomain: data.cookieDomain,
|
|
26
|
+
optOutByDefault: data.optOutByDefault !== undefined && data.optOutByDefault !== 'false',
|
|
27
|
+
respectDoNotTrack: data.respectDnt !== undefined && data.respectDnt !== 'false',
|
|
28
|
+
debug: data.debug !== undefined && data.debug !== 'false',
|
|
29
|
+
});
|
|
30
|
+
}
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import type { AnalyticsOptions, Properties } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Where events go unless the site says otherwise: Daybook's hosted API, which serves
|
|
4
|
+
* `/analytics/v1` beside the feedback ingest. As permanent as the wire itself, because it ships
|
|
5
|
+
* inside bundles cached on other people's pages.
|
|
6
|
+
*/
|
|
7
|
+
export declare const DEFAULT_API_URL = "https://api.daybook.team";
|
|
8
|
+
/**
|
|
9
|
+
* Product analytics for one site (PM-R-0062).
|
|
10
|
+
*
|
|
11
|
+
* const analytics = new DaybookAnalytics({ key: 'dak_…' })
|
|
12
|
+
* analytics.track('signed_up', { plan: 'pro' })
|
|
13
|
+
*
|
|
14
|
+
* Everything a product person needs from a page without a line of code — page views, sessions, where
|
|
15
|
+
* the visitor came from, browser and device — and `track` for the rest. Every method is safe to call
|
|
16
|
+
* on the server (Next.js, Nuxt), where it does nothing.
|
|
17
|
+
*/
|
|
18
|
+
export declare class DaybookAnalytics {
|
|
19
|
+
readonly options: AnalyticsOptions;
|
|
20
|
+
private readonly browser;
|
|
21
|
+
private readonly log;
|
|
22
|
+
private readonly store;
|
|
23
|
+
private readonly stateName;
|
|
24
|
+
private readonly context;
|
|
25
|
+
private readonly browserVersion;
|
|
26
|
+
private readonly outbox;
|
|
27
|
+
private readonly cleanup;
|
|
28
|
+
private state;
|
|
29
|
+
private current;
|
|
30
|
+
/** Where the page now shown was reached from: the last page of this app, or the document's referrer. */
|
|
31
|
+
private referrer;
|
|
32
|
+
private ignored;
|
|
33
|
+
constructor(options: AnalyticsOptions);
|
|
34
|
+
/** The anonymous id this browser sends events under. */
|
|
35
|
+
get distinctId(): string;
|
|
36
|
+
/** Who `identify()` said is signed in, or null. */
|
|
37
|
+
get userId(): string | null;
|
|
38
|
+
/** The current session's id; a new one starts after the session timeout without events. */
|
|
39
|
+
get sessionId(): string | null;
|
|
40
|
+
/** Whether events are being kept back: opted out, waiting for consent, Do Not Track, or a crawler. */
|
|
41
|
+
get optedOut(): boolean;
|
|
42
|
+
/** Properties sent with every event, from `register()`. */
|
|
43
|
+
get registered(): Readonly<Record<string, unknown>>;
|
|
44
|
+
/** Something the visitor did, with what describes it: `track('checkout_started', { plan: 'pro', seats: 3 })`. */
|
|
45
|
+
track(event: string, properties?: Properties): void;
|
|
46
|
+
/**
|
|
47
|
+
* A page view, with its URL, path, title, referrer and campaign. Sent by itself on load and on every
|
|
48
|
+
* navigation unless `autoPageviews` is false; call it yourself then, after the route has changed.
|
|
49
|
+
*/
|
|
50
|
+
page(properties?: Properties): void;
|
|
51
|
+
/**
|
|
52
|
+
* The visitor signed in as `userId`: their events from now on are theirs, and so is everything this
|
|
53
|
+
* browser sent before, without anything being sent again. Call it after every sign-in, and on every
|
|
54
|
+
* page load while they are signed in — a repeat costs nothing.
|
|
55
|
+
*
|
|
56
|
+
* A different user signing in on the same browser starts a new anonymous id first, because one
|
|
57
|
+
* anonymous id belongs to one person.
|
|
58
|
+
*/
|
|
59
|
+
identify(userId: string, properties?: Properties): void;
|
|
60
|
+
/**
|
|
61
|
+
* The visitor signed out: a new anonymous id and session, and the registered properties forgotten,
|
|
62
|
+
* so whoever uses this browser next is somebody new. Where the browser first came from is kept, and
|
|
63
|
+
* goes to the new person with their first event, as it went to the last.
|
|
64
|
+
*/
|
|
65
|
+
reset(): void;
|
|
66
|
+
/** Sets (and unsets) properties of the person: their plan, their company, their role. */
|
|
67
|
+
setPersonProperties(set: Properties, unset?: string[]): void;
|
|
68
|
+
/**
|
|
69
|
+
* Sets properties of the person only where they have no value yet — under this browser's ids or any
|
|
70
|
+
* other the person signed in with — so the first value stays: `{ first_plan: 'free', signed_up_at: new Date() }`.
|
|
71
|
+
* A later `setPersonProperties` still changes them.
|
|
72
|
+
*/
|
|
73
|
+
setPersonPropertiesOnce(properties: Properties): void;
|
|
74
|
+
private who;
|
|
75
|
+
/** Properties sent with every later event from this browser, kept across visits until `reset()`. */
|
|
76
|
+
register(properties: Properties): void;
|
|
77
|
+
unregister(name: string): void;
|
|
78
|
+
/** The visitor agreed: send from now on, and remember it. The page they are on is counted then. */
|
|
79
|
+
optIn(): void;
|
|
80
|
+
/** The visitor declined: send nothing, forget what was waiting, and keep only the choice. */
|
|
81
|
+
optOut(): void;
|
|
82
|
+
/** Sends what is waiting now. Resolves when it is sent or the API cannot be reached. */
|
|
83
|
+
flush(): Promise<void>;
|
|
84
|
+
/** Stops listening and sending; for tests and hot reload. */
|
|
85
|
+
destroy(): void;
|
|
86
|
+
private get sending();
|
|
87
|
+
private capture;
|
|
88
|
+
/** What a session began from: the referrer of the page it began on, and that page's campaign. */
|
|
89
|
+
private entry;
|
|
90
|
+
private emit;
|
|
91
|
+
/**
|
|
92
|
+
* The session an event at `now` belongs to (PM-R-0069 criterion 1): the current one, or a new one
|
|
93
|
+
* after the idle timeout or once the current one is a day old. It is kept with the rest of the state,
|
|
94
|
+
* so every tab of the site shares it, and `reset()` starts a new one.
|
|
95
|
+
*/
|
|
96
|
+
private session;
|
|
97
|
+
private leave;
|
|
98
|
+
/**
|
|
99
|
+
* Page views from the History API (PM-R-0062 criterion 3): every router of a single-page app moves
|
|
100
|
+
* through pushState, replaceState or popstate. A change of the query string alone is not a new page.
|
|
101
|
+
* The view is sent a moment later, so the router has set the new page's title.
|
|
102
|
+
*/
|
|
103
|
+
private watchHistory;
|
|
104
|
+
/**
|
|
105
|
+
* Before the page goes away, everything waiting is handed to the browser as beacons
|
|
106
|
+
* (PM-R-0062 criterion 4). Hidden comes first and is the last moment a phone reliably gives a page;
|
|
107
|
+
* pagehide is the page really leaving, which is also when it is left.
|
|
108
|
+
*/
|
|
109
|
+
private listen;
|
|
110
|
+
private on;
|
|
111
|
+
private load;
|
|
112
|
+
/**
|
|
113
|
+
* Picks up what another tab of the same site wrote — its sign-in, its reset, its session — so every
|
|
114
|
+
* tab sends as the same visitor. Only from storage that is being written; a page that keeps nothing
|
|
115
|
+
* has nothing to pick up.
|
|
116
|
+
*/
|
|
117
|
+
private sync;
|
|
118
|
+
/**
|
|
119
|
+
* Writes the state, only once the visitor may be tracked: before consent nothing identifying is
|
|
120
|
+
* stored, and after an opt-out only the choice is.
|
|
121
|
+
*/
|
|
122
|
+
private save;
|
|
123
|
+
}
|