@daybook/analytics 0.0.0-stage → 0.3.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 ADDED
@@ -0,0 +1,47 @@
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.3.0
7
+
8
+ More of where and on what an event happened, as context columns a question can filter and break down by
9
+ (PM-T-0613).
10
+
11
+ - The person's settings: `timezone` (IANA), `languages` (every preferred one, in order), `calendar`,
12
+ `numbering_system`, `hour_cycle`.
13
+ - The screen: `screen_width`, `screen_height`, `pixel_ratio`; `color_scheme` (light or dark); `network`
14
+ (the connection as the browser rates it, where it says).
15
+ - Chromium's client hints, where the browser gives them: an Android phone's `device_model`, and the real
16
+ `os_version` where the user agent is frozen (Windows 11, macOS).
17
+ - Nothing that singles a device out rather than describing it: no canvas, fonts, graphics card, audio or
18
+ hardware counts.
19
+
20
+ ## 0.2.0
21
+
22
+ Events at their true time, first touch on the person, and sessions as every Daybook SDK keeps them.
23
+
24
+ - Every batch carries `sent_at`, stamped as the request leaves — each retry and each beacon anew — so
25
+ Daybook places an event at the time it happened when the visitor's clock is wrong or the event waited
26
+ offline (PM-R-0068).
27
+ - `setPersonPropertiesOnce`: a person property written only where the person has none yet (PM-R-0067).
28
+ - Where the browser first came from (`$initial_referrer`, `$initial_referring_domain`, `$initial_utm_*`) is
29
+ set once on the person by itself, with the browser's first event, as `$set_once`.
30
+ - Sessions (PM-R-0069): a session also ends after 24 hours of steady use, and each opens with
31
+ `$session_start`, carrying the referrer and campaign it began from. Still shared by every tab, still new
32
+ after 30 minutes idle and on `reset()`.
33
+
34
+ ## 0.1.0
35
+
36
+ First release (PM-R-0062).
37
+
38
+ - `init` / `new DaybookAnalytics({ key })`; `track`, `page`, `identify`, `reset`, `setPersonProperties`,
39
+ `register` / `unregister`, `optIn` / `optOut`, `flush`.
40
+ - Page views on load and on every navigation of a single-page app, with `$pageleave` and time on page;
41
+ sessions after 30 minutes idle; UTM and referrer, with the browser's first ones kept as `$initial_*`.
42
+ - Batched delivery as CORS-simple requests; retry with backoff; `sendBeacon` when the page is hidden; a
43
+ queue in `sessionStorage` that survives a reload.
44
+ - Consent: `optOutByDefault`, `respectDoNotTrack`, `beforeSend`; crawlers left out.
45
+ - `@daybook/analytics/react` (`DaybookProvider`, `useAnalytics`) and `@daybook/analytics/vue`
46
+ (`createAnalytics`, `useAnalytics`, Vue Router page views).
47
+ - 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,447 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.3.0`
66
+ or `https://unpkg.com/@daybook/analytics@0.3.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, so a breakdown by them is fast:
411
+
412
+ - From the user agent: `browser`, `os`, `os_version`, `device_type`, `locale`, `app_version`. Where Chromium
413
+ answers its client hints, `device_model` (an Android phone's) and the real `os_version`.
414
+ - The person's settings: `timezone`, `languages`, `calendar`, `numbering_system`, `hour_cycle`.
415
+ - The screen and connection: `screen_width`, `screen_height`, `pixel_ratio`, `color_scheme`, `network`.
416
+
417
+ Daybook adds where the request came from, as its edge resolved it: `country`, and with location headers on,
418
+ `continent`, `region`, `region_code`, `city`, `postal_code`, `latitude`, `longitude` (and `timezone` when the
419
+ device sent none). The address itself is never stored — only a keyed hash of it, `ip_hash`.
420
+
421
+ `identify` goes to `/analytics/v1/identify` and person properties to `/analytics/v1/people`. A server can
422
+ call the same three endpoints with the key in an `X-Daybook-Key` header.
423
+
424
+ ## Troubleshooting
425
+
426
+ **Nothing on the Events page.** Turn on `debug: true` (or `data-debug`) and look at the console: every
427
+ event queued and every answer is logged. Then check **Analytics → Settings → Data health**, which shows the
428
+ last event received and anything refused, by reason.
429
+
430
+ **A warning names a refused event.** The reason says why: `reserved_event` for a `$` name,
431
+ `too_many_properties`, `properties_too_large`, `invalid_event` for a name over 200 characters.
432
+
433
+ **`the ingest key was refused`.** The key is wrong or revoked. Issue a new one in Settings.
434
+
435
+ **`identify was refused`.** That anonymous id already belongs to another user — two users signed in on
436
+ one browser without `reset()` between them, in two tabs at once. Call `reset()` on sign-out.
437
+
438
+ **Ad blockers.** The script is `daybook.js`, not `analytics.js`, so blockers that drop analytics scripts by
439
+ name pass it; some also block requests to analytics services. For the most complete numbers, install from
440
+ npm (bundled code has no script URL to block) and send through a path on your own domain that forwards to
441
+ `https://api.daybook.team/analytics/v1/`, then set `apiUrl` to your domain.
442
+
443
+ **Content Security Policy.** Allow `connect-src https://api.daybook.team` and, for the script tag,
444
+ `script-src https://daybook.team`.
445
+
446
+ **Local development.** Use a Development key so test traffic stays apart, and with a local Daybook point
447
+ `apiUrl` at it (`http://localhost:5099`).
@@ -0,0 +1 @@
1
+ export {};
@@ -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
+ }
@@ -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
+ }