JavaScript SDK
The same guide ships with the package, so what you read here matches what you install.
One app key is enough for development and release. Signals marked as debug are kept apart as test data. How Test mode works
Privacy-first analytics for web apps, browser games and Node.js. No cookies, no device IDs, offline queue, under 9 kB gzipped.
Docs: https://pulse.mightys.dev/docs/javascript/
MightyS Pulse lets a web app, a browser game or a Node.js service send named signals (events) with an optional number and a few properties, and see them in the Pulse dashboard. It sets no cookies, reads no advertising or device identifier and does no fingerprinting. It has zero runtime dependencies.
Install
npm install @mightys-dev/pulse
# or: pnpm add @mightys-dev/pulse
# or: yarn add @mightys-dev/pulseQuick start
Browser. Bundlers that honour the browser condition resolve the default import to the web build; the /web entry selects it explicitly.
import { Pulse } from '@mightys-dev/pulse/web';
Pulse.init('YOUR_APP_KEY', { appVersion: '1.0.0' }); // your app key from the Pulse dashboard
Pulse.track('purchase', { value: 4.99, props: { sku: 'gems_100', discounted: false } });
await Pulse.flush(); // optional: sends what is eligible nowNode.js (ESM; for CommonJS use const { Pulse } = require('@mightys-dev/pulse');):
import { Pulse } from '@mightys-dev/pulse';
Pulse.init(process.env.PULSE_APP_KEY, {
appVersion: '1.0.0',
storagePath: './.analytics/queue.json',
});
Pulse.track('job.complete', { value: 1, props: { job: 'daily-summary' } });
await Pulse.flush(); // Node installs no exit handler: flush before exitingNothing else is needed to count users in Node.js and in web apps shipped inside a native app. Optionally, await Pulse.setUser('stable-user-id') uses your own user id instead of the anonymous install id (see below).
Public calls do not throw and their promises do not reject. Signals tracked before init are kept (the newest 100) and sent afterwards. Only the first init call has an effect. No page, click or navigation signals are created automatically.
What is sent and what is never sent
Sent with every signal: your signal name, optional number and properties, a UTC timestamp, the debug flag, a random session id, the platform (web, node or mobile), coarse OS name and version when available, locale, your configured app version, and the SDK name and version. What else is sent depends on where the code runs. A field the platform cannot give is left out.
| Where | Extra fields |
|---|---|
| Node.js | Device: deviceType (desktop), architecture, runtimeVersion. Settings: timeZone, utcOffsetMinutes, language, preferredLanguage, region. App: isDebugBuild, plus appName and appBuildNumber if you pass them. Usage statistics (below). |
| Native app wrapper | Device: deviceType, deviceModel, targetEnvironment (capacitor, cordova or webview). Screen: screenWidth, screenHeight, screenScale, screenWidthPx, screenHeightPx, orientation. Settings and accessibility: colorScheme, reduceMotion, increaseContrast, invertColors, layoutDirection, timeZone, utcOffsetMinutes, language, preferredLanguage, region. Network: connectionType. App: isDebugBuild, plus appName and appBuildNumber if you pass them. Usage statistics (below). |
| Normal browser | Only: language, preferredLanguage, timeZone, utcOffsetMinutes, colorScheme, reduceMotion, increaseContrast, deviceType. No screen size, connection type or other values that help to recognise a device. Nothing is stored. |
Usage statistics (Node.js and native app wrappers): firstSessionDate, totalSessionsCount, distinctDaysUsed, distinctDaysUsedLastMonth, previousSessionSeconds, averageSessionSeconds, sessionSeconds, and isNewInstall during the first session. They are kept in one small file next to the install id (<storagePath>.usage, or usage-<first 16 hex of the app key hash> under ~/.mightys-pulse/) or, in a wrapper, in localStorage under mightys-pulse:usage:<app key>. Opt-out deletes them. If storage fails they are kept in memory for the process.
Automatic signals (Node.js and native app wrappers): pulse.session_started once per session, pulse.new_install on the first launch and pulse.app_updated (with previousVersion and previousBuild) when the app version or build changed since the last launch. At most one of each per session, usually far fewer. A normal browser sends none of them because it has nowhere to keep the statistics.
Sessions use a random id that changes after 30 minutes of inactivity.
Anonymous install id: random, created by the SDK on first launch, stored only in the app's own storage, deleted with the app, replaced after opt-out, sent only as a SHA-256 hash, not derived from any device identifier, not shared between apps. It is how users are counted without any setup. Where it lives depends on where the code runs:
- Node.js: a small file next to the queue file (
<storagePath>.install-id), or one file per app key under~/.mightys-pulse/in the default layout. All processes of one app share it. - Native app wrapper (a web game or app shipped inside an iOS or Android app, for example with Capacitor or Cordova, or in a WebView):
localStorageundermightys-pulse:install:<app key>, which belongs to the app. The wrapper is recognised from positive evidence only. - Normal browser: no identifier is stored on the device and no user hash is sent unless you call
setUser.
User id: optional. If you call setUser, the id is hashed with SHA-256 on the device and sent instead of the install id. The raw id is never stored or sent. The hash is pseudonymous and can link one user's signals. setUser(null) goes back to the install id (or to no user hash in a normal browser).
Never sent: cookies, advertising or device identifiers, device names, fingerprinting data (canvas, fonts, high-entropy Client Hints, and in a normal browser screen size and connection type), location, page URLs, referrers, page titles. Browsers add their ordinary User-Agent header to any request; the SDK adds nothing to it.
IP address: the SDK does not read or send the device's IP address as data. As with any HTTP request, the server sees the connection address, uses it only to derive a two-letter country code and does not store it.
Do not put personal data in signal names, properties or app versions: they are sent as given and, in the offline queue, stored unencrypted.
Options
| Option | Default | Accepted values |
|---|---|---|
host |
https://in.mightys.dev |
HTTP(S) base URL without credentials, query or fragment. An invalid host leaves the client uninitialized. |
flushIntervalSeconds |
20 |
Number from 1 to 3600. |
maxBatchSize |
100 |
Integer from 1 to 1000. |
maxQueueSize |
1000 |
Integer from 1 to 100000. |
maxQueueAgeDays |
7 |
Number up to 30. Values above 29 act as 29. |
gzip |
true |
Compresses request bodies above 1024 bytes. |
automaticScreenViews |
true |
Browser and native app wrappers: sends pulse.screen_view on route changes. false installs nothing. See Screen views below. |
automaticSignals |
true |
Node and native app wrappers: sends pulse.session_started, pulse.new_install and pulse.app_updated. It can only switch them off; see Settings from the portal below. |
debug |
development builds: true; otherwise false |
Marks signals as test data and enables warnings, which never contain signal or user data. See Test mode below. |
appVersion |
'' |
String of at most 512 UTF-16 code units. |
appBuildNumber |
'' |
Node and native app wrappers. String of at most 64 characters. |
appName |
'' |
Node and native app wrappers. String of at most 64 characters. |
storagePath |
per-process files under ~/.mightys-pulse/ |
Node only. A queue file for exactly one process; consent is stored in <storagePath>.consent, the install id in <storagePath>.install-id and the usage statistics in <storagePath>.usage and the portal settings in <storagePath>.config. |
Invalid numeric and boolean values fall back to their defaults.
Screen views
In a browser and in a native app wrapper the SDK sends a pulse.screen_view signal for the first page and for every route change (history.pushState, history.replaceState, back and forward, and hashchange). It has two props: screen and, once there was an earlier screen, previousScreen.
- The name is the route path only (the hash path for hash routers such as
#/level/3). Query, fragment, the full URL and the page title are never read. Numeric and uuid-like segments become:id, so/user/42/ordersis sent as/user/:id/orders. Names are at most 128 characters. - The same name twice in a row is sent once.
- A normal browser sends it too and stores nothing for it. Opt-out and
debugapply as for any signal. - The History API is wrapped once; the original method always runs first.
- To switch it off, pass
automaticScreenViews: false. Nothing is then wrapped or listened to. - Node.js never sends screen views on its own. In any environment,
Pulse.screen('Menu')sends one by name (the same limits and dedupe apply).
Settings from the portal
The portal can switch things off for your app without a package update: screen views, the automatic signals (together or one type at a time), and groups of fields (device, screen, settings, network, app, usage). Everything is on by default.
- The SDK asks for the settings once per launch, in the background, and never waits for the answer. A failed request changes nothing.
- In Node.js and native app wrappers the answer is kept next to the install id (
<storagePath>.config,config-<first 16 hex of the app key hash>under~/.mightys-pulse/, orlocalStorageundermightys-pulse:config:<app key>) and applies from the next launch. Opt-out deletes it with the rest. - A normal browser stores nothing: the settings are asked for once per page load and apply to the rest of that page. Signals sent before the answer arrives use the defaults.
- When the settings cannot be read (offline, an error, no answer yet), everything is on.
- Options in code can only switch things off:
automaticScreenViews: falseandautomaticSignals: falsestay off whatever the portal says, and they never turn on what the portal switched off. - A group that is switched off leaves its fields out of every signal. The base fields (platform, OS, app version, locale, SDK name and version, device model) are always sent.
- If you opt out and back in during a run, the settings are asked for again at the next launch.
Test mode
Every signal carries a debug flag. debug: true marks it as test data, and the dashboard's test mode switch chooses whether you see test or real signals. One app key serves both, so you need one key per app. An explicit debug option always wins. Without it, the choice is made once, at init:
- Node:
NODE_ENVset todevelopmentortestmeans test data. Anything else, including unset, means real data. - Browser: the SDK follows
process.env.NODE_ENVwhen your bundler replaces it at build time. A page without such a replacement counts as real data, so set the option yourself.
Pulse.init(key, { debug: location.hostname === 'localhost' }); // or, in Vite: { debug: import.meta.env.DEV }Delivery and offline behaviour
- Signals are batched. The first batch is sent as soon as possible; later batches follow the interval or the batch size, whichever comes first.
- The queue is persisted (localStorage in browsers, files in Node) and survives reloads and restarts. Oldest signals are dropped first when the queue is full or expired.
- Failed requests (network errors, 408, 425, 429, 5xx) are retried with exponential backoff from 1 second to 5 minutes, honouring
Retry-Afterup to one hour. A 401 keeps the queue and stops sending until reload. - When the server asks for a pause or a different interval, the SDK follows it.
- In browsers, when the page is hidden or unloading, the SDK makes one best-effort keepalive request. If the browser drops it, the signals stay queued and are sent from the next page.
- Each batch carries an id, so a batch sent again after a lost answer is stored only once.
- Delivery is at least once: a signal can arrive twice, for example when a response is lost after the server accepted the request.
- Each browser tab keeps its own queue. A queue left by a closed tab is adopted by the next tab that starts. In Node, queue files of exited processes are adopted at start.
- Request bodies are gzipped when larger than 1024 bytes and never exceed 1 MiB or 1000 signals.
Requirements
| Supported | |
|---|---|
| Node.js | 22.12 and newer (native fetch). |
| Browsers | ES2022. fetch and TextEncoder are required for sending. Persistence, gzip and user hashing (WebCrypto, which needs HTTPS) degrade safely when unavailable. |
| Module formats | ESM and CommonJS, with TypeScript declarations for both. |
Opt-out
Pulse.optOut(true) clears pending signals, the user hash and the stored install id, cancels active requests where possible and stores the choice. Nothing is collected or sent while it is on. Other open tabs of the same site apply it at once. Requests already sent cannot be recalled. Pulse.optOut(false) turns collection back on with a new install id; a user hash from setUser needs a new setUser call. If the stored choice cannot be read, the SDK counts as opted out.
Licence
MIT.
Reference
| Call | Behaviour |
|---|---|
Pulse.init(key, options?) |
Initializes once per module instance. |
Pulse.track(type, { value?, props? }?) |
Queues a signal. |
await Pulse.setUser(id) |
Optional. Hashes your id locally and uses it instead of the anonymous install id. null or an empty string goes back to the install id. Await it before tracking signals that should carry the new hash. If hashing fails, signals carry the install id hash. |
await Pulse.flush() |
Waits for initialization, persistence and the sends that are eligible now. It returns after an offline failure or a server pause and does not wait through backoff. |
Pulse.optOut(enabled) |
See Opt-out. |
PulseOptions, TrackOptions and PulseClient are exported types.
Signal rules: the name needs non-whitespace content and at most 200 UTF-16 code units. The value must be a finite number or null. Props accept strings, finite numbers and booleans (sent as "true" or "false"); other props are discarded. A signal whose props exceed 8192 UTF-8 bytes is discarded. Lone UTF-16 surrogates become U+FFFD.
Browser storage: the key mightys-pulse:<app key> holds only the consent choice (plus mightys-pulse:install:<app key> with the install id, only inside a native app wrapper), and each page keeps its queue under its own key, removed while empty. Node: with the default location, every process writes its own queue file under ~/.mightys-pulse/ and the processes share one consent file, one install id file and one usage statistics file; consent changes reach other running processes at their next start.