Web SDK reference

@analyticstrend/web. For ordinary websites.

init(options)

Call once per page load. Returns a client.

const analytics = init({ writeKey: "wk_..." });

Option	Type	Default	Notes
writeKey	string	required	From your dashboard's Settings screen. Public by design.
endpoint	string	https://analyticstrend.com	Point at your own collector when self-hosting.
appVersion	string	none	Your site's version, so you can compare releases.
onError	(error) => void	none	Diagnostic only. Deliberately has no default, because this runs in your page and we do not get to decide what lands in your console.

Returns { track, flush }.

init also registers handlers for pagehide and for the tab becoming hidden, and sends anything left over from a previous visit as soon as it starts.

client.track(name, props?)

Queues an event.

analytics.track("page_view", { path: location.pathname });

The name must match ^[a-z0-9_]{1,64}$. An invalid name is reported through onError and never enters the queue.

client.flush()

Sends everything queued. Always resolves, never rejects.

You rarely need it: the unload handlers cover leaving the page, and the queue sends itself at 50 events.

Single-page applications

init runs once per document load, so client-side navigation fires nothing. Track route changes yourself, or your page-view numbers count first loads only. See the install guide.

Running more than one instance on a page

Supported. A tag manager and a hardcoded snippet can coexist, and each write key gets its own queue, so one product's events are never billed to another.

Storage that refuses to work

Safari's private browsing, a blocked third-party frame, and a site over quota all make browser storage throw — in some cases on the property access itself, before any read. The SDK falls back to an in-memory queue. Events still send during that visit; they do not survive a reload. Your page is never taken down by this script.

Sending as the page unloads

The final send uses the browser's keep-alive mechanism so it survives the page going away. Browsers cap those requests at 64 KB, so an unusually large queue omits the guarantee for that one send rather than failing: the events stay queued and go out on the next page load.

What the SDK guarantees

• Nothing is lost to a reload. Events are persisted before any send.
• Nothing is sent twice. Progress is recorded after every batch.
• The queue is bounded at 500 events, dropping the oldest first.
• Retries back off 30 seconds after a failure, so an offline visitor does not make one request per event.