deloryx-js
v0.3.1
Published
Deloryx first-party browser tracking library. Captures pageviews, autocapture clicks/submits, custom events, identify, and (lazy) error+perf monitoring. Posts to ping.deloryx.com.
Downloads
163
Readme
deloryx-js
First-party browser tracking library for the Deloryx platform. Captures pageviews, autocapture click/submit events, custom events, identify, and (lazy-loaded) error + perf monitoring. POSTs envelopes to ping.deloryx.com.
Install
npm install deloryx-jsOr, on a customer marketing site, paste the boot snippet (the contents of dist/snippet.js, minified to < 400 bytes) into <head>:
<script>
!function(d,t){if(!d.dtrack){d.dtrack=function(){(d.dtrack.q=d.dtrack.q||[]).push(arguments)};
d.dtrack.q=[];var s=document.createElement('script');s.async=1;s.src=t;
document.head.appendChild(s)}}(window,'https://ping.deloryx.com/t.js');
dtrack('init',{projectKey:'dlx_pub_YOURKEY'});
dtrack('track','$pageview');
</script>Quick start (Angular / bundler)
import { init, track, identify } from 'deloryx-js';
init({
projectKey: 'dlx_pub_deloryx_dot_com',
apiHost: 'https://ping.deloryx.com',
autocapture: true,
capturePageviews: true,
errors: true, // lazy-loads the errors chunk
perf: true,
});
track('checkout_started', { plan: 'pro', priceUsd: 49 });
identify('user_123', { email: '[email protected]', plan: 'pro' });Public API
| Function | Purpose |
|---|---|
| init(opts) | Initialize the tracker. Idempotent. |
| track(name, props?) | Capture a custom event. |
| identify(userId, traits?, traitsOnce?) | Bind anonymous → identified. Emits $identify with previousDistinctId. |
| setUserProperties(props) | Update user properties without rebinding identity. |
| reset() | Clear identity (after logout). |
| optIn() / optOut() | Sticky consent preference. |
| flush() | Force-flush the queue. Returns a promise. |
Build outputs
| File | Format | Use |
|---|---|---|
| dist/index.esm.js | ESM | npm consumers, bundlers |
| dist/index.cjs.js | CJS | Node tests, SSR shims |
| dist/t.js | IIFE | CDN bundle served at https://ping.deloryx.com/t.js |
| dist/errors.js | IIFE | Lazy chunk for error + perf integrations |
| dist/snippet.js | IIFE | The < 400 byte boot snippet |
Size budgets are enforced by size-limit — see package.json.
Testing
npm test # vitest unit tests (happy-dom)
npm run test:integration # playwright (requires dist/t.js built and copied to tests/fixtures/)
npm run typecheck # tsc --noEmit
npm run size # size-limit verificationArchitecture
See /home/sd/.claude/plans/we-need-to-implement-resilient-giraffe.md for the full design rationale, reference-library research, and design rules.
Key principles:
- Core bundle ≤ 10 KB gzip; everything else is a lazy chunk.
- Transport chain:
sendBeacon→fetch({keepalive:true})→fetch. - 30s / 50 events / 32 KB batching. Flush on
visibilitychange:hiddenandpagehide(NOTbeforeunload— unreliable on iOS). - UUID v7 anonymous IDs, dual-write localStorage + first-party cookie.
identify()sendspreviousDistinctIdso the server can link histories.- Default: no form values, no password inputs ever, opt-in via
data-dtrack-capture-value.