@nexly/web

Browser ingest SDK for Nexly: sendBeacon transport, DOM metadata, engagement listeners. Implements the abstract NexlyBase from @nexly/core for the browser runtime.

Install

npm install @nexly/web

Usage

import { Nexly } from '@nexly/web'

const client = Nexly.init({
  appId: 'your-app-id',
  key: 'your-ingest-key',
})

client.pageview()
client.event({ name: 'cta_clicked', type: 'custom', data: { placement: 'hero' } })

const stopEngagement = client.startEngagement()
// stopEngagement() on SPA unmount / route change if needed

startEngagement() is idempotent — calling it again stops the previous subscription first, so HMR or double-mounts can't produce duplicate listeners.

Opting elements out of auto-capture

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:

<button data-nexly-ignore onClick={() => client.event({ name: 'signup_clicked', type: 'custom' })}>
  Sign up
</button>

What you get

• Nexly — browser client (auto session + visitor IDs via localStorage/sessionStorage).
• collectSessionMeta(), collectEventMeta(), collectBrowserMeta() — reusable metadata collectors.
• startEngagementTracking(creds) — standalone engagement attach (scroll / click / focus / visibility / keepalive).
• sendBeaconCollect(input) — raw sendBeacon helper.

For React bindings use @nexly/react-web; for Next.js App Router use @nexly/next; for React Native use @nexly/react-native; for Node.js servers use @nexly/node.

Linking backend events to this visitor

If you also emit server-side events with @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.

import { getVisitorId, getSessionId } from '@nexly/web'

// once per signed-in user — send to your own backend
await fetch('/api/link-visitor', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    visitorId: getVisitorId(),
    sessionId: getSessionId(), // optional
  }),
})

getVisitorId() reads the persistent anonymous id Nexly stores in localStorage; getSessionId() reads the 30-minute tab session id from sessionStorage. Both are plain strings, safe to call from anywhere.

See the full recipe (backend storage + emitting linked events) in the @nexly/node README.

Bot detection

Bots and AI crawlers are classified server-side from the HTTP User-Agent header at ingest — do not try to compute or send an is_bot flag from your page code. Every event is stored (bots are not filtered out); the dashboard surfaces them in the dedicated "AI & Crawler activity" section and excludes them from standard visitor metrics.