@nexly/web 0.15.3 → 0.16.0

package/README.md

@@ -19,7 +19,7 @@ const client = Nexly.init({
 })
 
 client.pageview()
-client.event({ name: 'cta_clicked', type: 'custom', data: { placement: 'hero' } })
+client.customEvent('cta_clicked', { placement: 'hero' })
 
 const stopEngagement = client.startEngagement()
 // stopEngagement() on SPA unmount / route change if needed
@@ -32,7 +32,7 @@ const stopEngagement = client.startEngagement()
 Auto-click and auto-focus listeners skip any element (or descendant of an element) marked with `data-nexly-ignore`. Use it on elements where you already emit your own `event(...)` to avoid semantic duplicates:
 
 ```tsx
-<button data-nexly-ignore onClick={() => client.event({ name: 'signup_clicked', type: 'custom' })}>
+<button data-nexly-ignore onClick={() => client.customEvent('signup_clicked')}>
   Sign up
 </button>
 ```
@@ -46,6 +46,32 @@ Auto-click and auto-focus listeners skip any element (or descendant of an elemen
 
 For React bindings use [`@nexly/react-web`](https://www.npmjs.com/package/@nexly/react-web); for Next.js App Router use [`@nexly/next`](https://www.npmjs.com/package/@nexly/next); for React Native use [`@nexly/react-native`](https://www.npmjs.com/package/@nexly/react-native); for Node.js servers use [`@nexly/node`](https://www.npmjs.com/package/@nexly/node).
 
+## Custom analytics events
+
+For application-specific events use the ergonomic `customEvent` API. It takes three arguments and always emits an `event_type: 'custom'` event:
+
+```ts
+client.customEvent('checkout_completed', {
+  plan_id: 'pro',
+  amount_cents: 4200,
+  items: 3,
+})
+```
+
+- **`name`** — registered as a custom analytics event in the dashboard. Unapproved names show up under Discovered for later approval and do not enter analytics until you accept them.
+- **`cdata`** — user-defined custom properties. Values must be `string`, `number`, or `boolean`; numbers and booleans are normalised to strings server-side. Nested objects, arrays, and `null` are silently dropped.
+- **`context`** *(optional)* — per-event attribution override for the standard marketing parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `gclid`, `gad_source`, `gad_campaignid`, `fbclid`, `msclkid`, `ttclid`, `li_fat_id`, `yclid`, `mc_cid`, `ref`). Useful when the landing URL no longer carries them at click time (single-page navigation, deep-links, post-redirect flows). Only standard attribution keys are accepted in this slot.
+
+```ts
+client.customEvent(
+  'signup_clicked',
+  { source_section: 'pricing' },
+  { utm_source: 'newsletter', utm_campaign: 'q2-launch' },
+)
+```
+
+The generic `client.event({ name, type, cdata, data, context })` remains available when you need to set Nexly-known context fields like `visitor_id` alongside custom properties.
+
 ## Linking backend events to this visitor
 
 If you also emit server-side events with [`@nexly/node`](https://www.npmjs.com/package/@nexly/node) and want them to show up on the same user timeline as browser activity, forward the browser's Nexly visitor id to your backend once (on sign-up / login), persist it next to your own user record, and pass it through in `context` when emitting backend events.

package/dist/browser-meta.d.ts

@@ -5,7 +5,7 @@
  */
 /** Session-stable metadata: user agent, screen, language, timezone, etc. */
 export declare function collectSessionMeta(): Record<string, unknown>;
-/** Per-event volatile metadata: visitor/session IDs, current URL/pathname. */
+/** Per-event volatile metadata: visitor/session IDs, current URL/path. */
 export declare function collectEventMeta(): Record<string, unknown>;
 /** Legacy: full browser metadata (session + event merged). */
 export declare function collectBrowserMeta(): Record<string, unknown>;

package/dist/browser-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-meta.d.ts","sourceRoot":"","sources":["../src/browser-meta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,4EAA4E;AAC5E,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4E5D;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB1D;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5D"}
+{"version":3,"file":"browser-meta.d.ts","sourceRoot":"","sources":["../src/browser-meta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,4EAA4E;AAC5E,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4E5D;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAe1D;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5D"}

package/dist/browser-meta.js

@@ -88,7 +88,7 @@ export function collectSessionMeta() {
     }
     return filterEmpty(out);
 }
-/** Per-event volatile metadata: visitor/session IDs, current URL/pathname. */
+/** Per-event volatile metadata: visitor/session IDs, current URL/path. */
 export function collectEventMeta() {
     if (typeof window === 'undefined' || typeof navigator === 'undefined') {
         return {};
@@ -98,7 +98,6 @@ export function collectEventMeta() {
     out.session_id = safe(() => getSessionId());
     out.url = safe(() => window.location.href);
     const pathname = safe(() => window.location.pathname);
-    out.pathname = pathname;
     // Engagement/lifecycle events dispatch directly via sendBeaconCollect and
     // bypass NexlyBase.dispatch (which adds `path` from getDefaultPath). Include
     // `path` here so every event carries it.

package/dist/index.d.ts

@@ -7,6 +7,6 @@ export { collectBrowserMeta, collectSessionMeta, collectEventMeta } from './brow
 export { getSessionId, getVisitorId } from './session.js';
 export { sendBeaconCollect, type SendBeaconCollectInput } from './beacon.js';
 export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking, startOutboundLinkTracking, } from './events/index.js';
-export type { CollectCredentials, IngestCredentials, TrackEventInput } from '@nexly/core';
+export type { CData, CollectCredentials, IngestCredentials, StandardContextOverride, TrackEventInput, } from '@nexly/core';
 export { buildCollectPayload } from '@nexly/core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EACV,KAAK,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexly/web",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Nexly browser ingest SDK: sendBeacon transport, DOM metadata, engagement listeners on top of @nexly/core",
   "license": "MIT",
   "keywords": [
@@ -38,7 +38,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@nexly/core": "0.15.3"
+    "@nexly/core": "0.16.0"
   },
   "devDependencies": {
     "typescript": "~6.0.2"