@indiebob/tracker 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,86 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.3.0] — 2026-11-01
+
+The npm module bundles (`index.js`/`.cjs`, `vue.js`/`.cjs`) are no longer
+minified — your bundler minifies them. A minified bundle's comma-joined
+declarations slipped past Nuxt's auto-import scanner and broke a Nuxt build.
+The script-tag bundle (`indiebob.min.js`) stays minified, under 5 KB.
+
+Needs the matching `/api/collect` (it must accept `type: 'engagement'` and
+the new top-level `id` and `engagement` fields) **before** this version is
+served: the 0.2 server rejects a whole batch that contains an engagement event.
+
+### Added
+- **Self-initialising script tag.** `<script src=".../indiebob.min.js"
+  data-project="proj_…" defer></script>` initialises itself and tracks the
+  page plus every SPA navigation, with no `init()` / `page()` call. Optional
+  `data-api` (endpoint), `data-auto-page="false"` (initialise only),
+  `data-hash-mode="true"`. A tag without `data-project` behaves exactly as
+  before.
+- **Event id.** Every event carries a top-level `id` (21 url-safe
+  characters), unchanged across retries and offline replays, so the server
+  can store each event once. Server-side events (`/server`) carry one too.
+- **`engagement` event.** Visible-and-focused milliseconds and the deepest
+  scroll depth (% of the page) for the page it describes, with that page's
+  context. Sent on tab hide, pagehide and right before an SPA navigation,
+  only when the scroll grew or ≥ 3 s accumulated since the last one; never a
+  pageview.
+- **Automatic file downloads.** A click on a link to a file (pdf, zip, dmg,
+  exe, msi, pkg, apk, ipa, deb, rpm, appimage, archives, office files, txt,
+  epub, mp3/wav/mp4/mov, iso) fires `file_download` with
+  `{ url, path, ext, auto: true }`, on any host; `url` drops the query and
+  hash. An outbound download fires only `file_download`. Off with
+  `autoDetect: { fileDownloads: false }`.
+- **Owner self-exclude.** `?ib_ignore=1` stops this browser being counted
+  (stored as `localStorage.ib_ignore`, with one console line per page load);
+  `?ib_ignore=0` undoes it. `bob.isIgnored()` reports it.
+- **`hashMode`** option for `/#/route` routers.
+
+### Changed
+- A `page()` for the path already counted (same pathname + query; a
+  hash-only change unless `hashMode`) is skipped.
+- A back/forward-cache restore (`pageshow` with `persisted`) counts as a
+  pageview.
+- A page that is prerendered or opened in a background tab counts its first
+  pageview when it is first shown.
+- `navigator.webdriver` browsers send nothing.
+- `init()` with a `projectId` that is already running returns that instance
+  (the first config wins) instead of starting a second tracker.
+- Builds: the script-tag bundle targets ES2020 (Chrome 80, Firefox 74,
+  Safari 13.1) and the npm ESM/CJS build ES2018 (was ES2015 for both) — the
+  price of staying under 5 KB gzipped with the features above. Private
+  members are shortened at build time.
+- The plain-http fallback for the session id (no `crypto.randomUUID` outside
+  a secure context) now uses the SDK's crypto id generator instead of
+  `Math.random`.
+
+---
+
+## [0.2.4] — 2026-09-08
+
+### Added
+- **`identify(userId, traits, { isNew })` — tell us, don't make us guess.**
+  Without the hint, signup-vs-login is decided by a localStorage flag the SDK
+  wrote itself, and that flag cannot exist in a browser that has never called
+  `identify()`. So on a product that already has users, the day you install
+  `identify()` **every returning user files a phantom `signup`** and the top of
+  your funnel is wrong from then on. Your server knows whether it just created
+  the user row — pass `isNew` and the guess is skipped.
+
+  Additive and fully backwards compatible: two-argument calls behave exactly as
+  before. The emitted event now carries `properties.auto`, which is `false`
+  when the verdict came from your server and `true` when it was inferred, so a
+  funnel that looks wrong later can be traced to a guess.
+
+  ```js
+  bob.identify('user_123', { plan: 'pro' })                  // inferred
+  bob.identify('user_123', { plan: 'pro' }, { isNew: true }) // server truth
+  ```
+
+---
+
 ## [0.2.1] — 2026-08-24
 
 ### Fixed

package/README.md

@@ -10,12 +10,15 @@ npm install @indiebob/tracker
 pnpm add @indiebob/tracker
 ```
 
-Or via script tag (CDN):
+Or via script tag (CDN) — one line, nothing else to write:
 
 ```html
-<script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js"></script>
+<script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js" data-project="proj_your16charId" defer></script>
 ```
 
+The tag initialises itself from `data-project` and tracks this page plus every
+SPA navigation. See [Script tag](#vanilla-js-script-tag) for the options.
+
 ## Quick Start
 
 Three lines to start tracking:
@@ -39,6 +42,7 @@ const bob = IndieBob.init({
   respectDnt: true,       // Optional. Honor browser Do Not Track. Default: true.
   respectGpc: true,       // Optional. Honor Global Privacy Control. Default: true.
   autoDetect: true,       // Optional. Auto-detect signups, logins, checkouts, etc. Default: true.
+  hashMode: false,        // Optional. Treat the URL hash as part of the path (/#/route routers). Default: false.
 })
 ```
 
@@ -49,7 +53,8 @@ const bob = IndieBob.init({
 | `debug` | `boolean` | `false` | Log all events to browser console |
 | `respectDnt` | `boolean` | `true` | Honor the browser's Do Not Track header |
 | `respectGpc` | `boolean` | `true` | Honor Global Privacy Control signal (legally binding in CA/GDPR) |
-| `autoDetect` | `boolean \| object` | `true` | Auto-detect user intent from URL patterns, form submissions, outbound clicks, and data attributes. See [Auto-Detection](#auto-detection). |
+| `autoDetect` | `boolean \| object` | `true` | Auto-detect user intent from URL patterns, form submissions, outbound clicks, file downloads, and data attributes. See [Auto-Detection](#auto-detection). |
+| `hashMode` | `boolean` | `false` | Count a hash-only change as a new page and report the hash in the path. For hash routers (`/#/settings`). |
 
 ## API Reference
 
@@ -61,6 +66,10 @@ Creates and returns a tracker instance. Call once at app startup.
 const bob = IndieBob.init({ projectId: 'proj_abc123def456ghij' })
 ```
 
+Calling `init()` again with the same `projectId` returns the instance that is
+already running (the first config wins), so nothing is ever counted twice —
+for example a `data-project` script tag plus your own `init()` call.
+
 ---
 
 ### `bob.page(overrides?)`
@@ -75,6 +84,12 @@ bob.page({ title: 'Pricing Page' }) // Override title
 
 **Auto-detected:** URL path, page title, referrer, UTM parameters, device type.
 
+A `page()` for the path you are already on (same pathname + query) is skipped,
+so a framework hook that fires twice, or a hash-only change, never counts a
+second view. A page restored from the back/forward cache counts again. A page
+that is prerendered or opened in a background tab is counted when it is first
+shown, not before.
+
 ---
 
 ### `bob.track(event, properties?)`
@@ -136,8 +151,22 @@ bob.revenue({
 bob.optOut()       // Stop all tracking. Clears all stored identifiers.
 bob.optIn()        // Re-enable tracking.
 bob.isOptedOut()   // Returns boolean.
+bob.isIgnored()    // True if this browser excluded itself with ?ib_ignore=1.
 ```
 
+### Exclude your own visits (`ib_ignore`)
+
+Open your site once with `?ib_ignore=1` on the URL
+(`https://yoursite.com/?ib_ignore=1`). That browser stops being counted — on
+every page, from then on — and the console says
+`IndieBob: this browser is excluded from analytics (ib_ignore)` on each page
+load so you can see it working. Open any page with `?ib_ignore=0` to be counted
+again. It is stored in `localStorage` as `ib_ignore`, so it is per browser and
+per site. Your identifiers are kept (unlike `optOut()`).
+
+Browsers driven by automation (`navigator.webdriver` — Playwright, Selenium,
+Puppeteer, headless test runners) send nothing at all.
+
 ---
 
 ### Debug / Testing
@@ -188,6 +217,40 @@ On signup, login, and checkout pages, form submissions are automatically tracked
 
 Clicks on links pointing to external domains automatically fire `outbound_click` with `{ url, hostname }` properties.
 
+### File Download Tracking
+
+A click on a link whose path ends in a file extension fires `file_download`
+with `{ url, path, ext }` — on your own host or any other (a GitHub release,
+a CDN). `url` is the link without its query string or hash, so a signed
+download token never reaches your analytics. A download on another host fires
+only `file_download`, not `outbound_click` as well.
+
+Extensions: `pdf zip dmg exe msi pkg apk ipa deb rpm appimage gz tgz bz2 xz
+tar 7z rar csv xls xlsx doc docx ppt pptx txt epub mp3 wav mp4 mov iso`.
+
+```html
+<a href="/downloads/MyApp-2.1.dmg">Download for Mac</a>
+<!-- → track('file_download', { url: 'https://yoursite.com/downloads/MyApp-2.1.dmg',
+                                path: '/downloads/MyApp-2.1.dmg', ext: 'dmg', auto: true }) -->
+```
+
+Turn it off with `autoDetect: { fileDownloads: false }`.
+
+### Engagement (time on page and scroll depth)
+
+After `page()`, the SDK measures how long the page was **visible and focused**
+(a background tab or another focused window does not count) and how far down
+it was read (the deepest point seen, as a percentage of the page height). It
+sends this as an `engagement` event — never a pageview — with the context of
+the page it describes:
+
+- when the tab is hidden or the page is closed (by beacon, like every last event);
+- right before an SPA navigation, for the page being left.
+
+It is sent only when there is something new: the scroll depth grew, or at
+least 3 seconds of engaged time accumulated since the last one. The counters
+start again for every page. Nothing to set up.
+
 ### Data Attribute Tracking
 
 Add `data-ib-event` to any element for zero-JS custom event tracking:
@@ -214,6 +277,7 @@ const bob = IndieBob.init({
 
     // Disable specific features
     outboundClicks: false,
+    fileDownloads: false,
     formSubmit: false,
     dataAttributes: false,
   },
@@ -234,6 +298,7 @@ Set `autoDetect: false` to disable all auto-detection entirely.
 | `dataAttributes` | `boolean` | `true` | Track clicks on `data-ib-event` elements |
 | `formSubmit` | `boolean` | `true` | Track form submissions on intent pages |
 | `outboundClicks` | `boolean` | `true` | Track clicks on external links |
+| `fileDownloads` | `boolean` | `true` | Track clicks on links to files as `file_download` |
 
 ---
 
@@ -288,6 +353,37 @@ useEffect(() => {
 
 ### Vanilla JS (Script Tag)
 
+One tag, before `</head>` on every page:
+
+```html
+<script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js" data-project="proj_abc123def456ghij" defer></script>
+```
+
+It initialises itself and tracks the page plus every SPA navigation
+(`pushState` / back / forward) — no `init()` or `page()` call. Attributes:
+
+| Attribute | Meaning |
+|---|---|
+| `data-project` | Your project ID. Without it the tag does nothing on its own. |
+| `data-api` | Ingestion endpoint override (self-hosted). |
+| `data-auto-page="false"` | Initialise only; you call `page()` yourself. |
+| `data-hash-mode="true"` | Same as the `hashMode` option. |
+
+To call `track()` / `identify()` from your own script, ask for the running
+instance — `init()` with the same project ID returns it. With `defer`, the
+global exists once the document has been parsed:
+
+```html
+<script>
+  document.addEventListener('DOMContentLoaded', function () {
+    var bob = IndieBob.init({ projectId: 'proj_abc123def456ghij' })
+    bob.track('newsletter_signup')
+  })
+</script>
+```
+
+The classic install keeps working unchanged:
+
 ```html
 <script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js"></script>
 <script>
@@ -296,6 +392,11 @@ useEffect(() => {
 </script>
 ```
 
+If you add `data-project` to that same tag (leave out `defer` while the inline
+call is there — a deferred script runs after it), nothing is counted twice:
+`init()` returns the running instance and the second `page()` for the same
+path is skipped.
+
 ### Server-Side (Node.js)
 
 ```ts
@@ -330,6 +431,12 @@ UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_con
 - **Last-touch** attribution in `_ib_last_utm` — updated each time UTMs are present in the URL
 - Enables "which campaign drove this paying customer?" — the core attribution question
 
+### Event IDs
+
+Every event carries a random, url-safe `id` (21 characters). It stays the same
+when a batch is retried or replayed from the offline queue, so the server
+stores each event once.
+
 ### Event Batching
 
 Events are batched for efficiency:
@@ -360,6 +467,8 @@ The SDK respects:
 | UTM params | From URL query string | Object |
 | Screen size | `window.innerWidth/Height` | Numbers |
 | Device type | Derived from screen size | `'desktop'` \| `'mobile'` \| `'tablet'` |
+| Engaged time | Visible-and-focused milliseconds on the page (`engagement` event) | Number |
+| Scroll depth | Deepest point of the page seen, % of its height (`engagement` event) | Number |
 | Browser locale | `navigator.language` | String |
 | Timezone | `Intl.DateTimeFormat().resolvedOptions().timeZone` | String |
 | Country | Derived server-side from IP | String (e.g. `'US'`) |
@@ -381,6 +490,7 @@ The SDK respects:
 | `onboarding_view` | User visits an onboarding page |
 | `contact_view` | User visits a contact page |
 | `outbound_click` | User clicks an external link |
+| `file_download` | User clicks a link to a file (pdf, zip, dmg, …) |
 | Custom via `data-ib-event` | User clicks an element with the attribute |
 
 ### NOT collected
@@ -401,6 +511,9 @@ The SDK does not use cookies and does not collect personal data by default. The
 
 When a user calls `optOut()`, all stored keys are cleared: `_ib_anon`, `_ib_session`, `_ib_first_utm`, `_ib_last_utm`, `_ib_referrer`, `_ib_queue`.
 
+`ib_ignore` (the site owner's own self-exclusion, see above) is the one key the
+SDK writes that is not an identifier; it is removed with `?ib_ignore=0`.
+
 ### CCPA (California)
 
 Global Privacy Control (GPC) is automatically honored. If a user has GPC enabled in their browser, the SDK sends no events. This is the legally correct behavior under CCPA as amended by CPRA.
@@ -441,14 +554,20 @@ This SDK follows [Semantic Versioning](https://semver.org/).
 
 ## Bundle Size
 
-| Bundle | Size (gzip) |
+| Bundle | Size (gzip -9) |
 |---|---|
-| Browser IIFE (`tracker.js`) | < 5KB |
-| ESM tree-shakeable | < 4KB |
+| Browser IIFE (`indiebob.min.js`) | < 5KB (5,076 bytes in 0.3.0) |
+| ESM (`index.js`) | ~5KB (5,135 bytes in 0.3.0; your bundler minifies and tree-shakes it further) |
 | Server (Node.js) | No limit |
 
 Zero runtime dependencies.
 
+## Browser Support
+
+The script-tag bundle targets ES2020: Chrome/Edge 80+, Firefox 74+, Safari
+13.1+ (iOS 13.4+). The npm build (ESM/CJS) targets ES2018 and is transpiled
+further by your bundler if you need older browsers.
+
 ---
 
 ## License