@prodantix/sdk
v0.11.0
Published
Prodantix analytics + feature-flag client SDK (isomorphic, zero-dependency)
Readme
Prodantix SDK
Isomorphic, zero-dependency analytics + feature-flag client for Prodantix. Runs in the browser, Node, and edge runtimes. Ships dual ESM/CJS with full TypeScript types.
Docs
- Quickstart: install and send a first event
- Get an API key: signup, project creation, where the key lives
- API reference: every REST operation, rendered
- React apps: pair with
@prodantix/react, the provider + hook adapter
Install
bun add @prodantix/sdkBrowser
import { createWebClient } from '@prodantix/sdk/web'
// PRODANTIX_PUBLIC_KEY is your pdx_pub_… project key, injected at build time.
const prodantix = createWebClient({
apiKey: PRODANTIX_PUBLIC_KEY,
host: 'https://eu.api.prodantix.com',
flagsHost: 'https://api.prodantix.com',
})
prodantix.capture('order.completed', { properties: { amount: 4200, currency: 'XAF' } })
prodantix.identify('user-42', { set: { plan: 'pro' } })
if (await prodantix.isFeatureEnabled('new-checkout')) {
// ...
}createWebClient keeps the visitor's anonymous id and session in a first-party cookie on the
registrable domain, so xyz.com, app.xyz.com and console.xyz.com see one person; the
identified id stays per origin in localStorage and never enters the cookie. Pass cookieDomain
to name the domain (a site whose subdomains belong to different tenants must), or sharedStorage
to write no cookie. The queue persists in localStorage, a batch sent while the page is
hidden goes by a keepalive fetch so it outlives the page, and pageviews and clicks are autocaptured. Pass autocapture: false to disable
capture, or autocaptureOptions: { pageviews, clicks } to tune it.
Autocapture collects no customer content by default. A click records the element's tag, id and
classes and the link it points at, but not the element's text unless you pass
autocaptureOptions: { captureElementText: true }. Every captured address, $current_url,
$referrer and a link's $el_href, keeps its origin and path and drops its query and fragment,
where tokens, invite codes and email addresses travel; a link that is not a web address keeps
only its scheme, such as mailto:. Mark an element with data-pdx-no-capture or the
pdx-no-capture class, or list CSS selectors in autocaptureOptions.maskSelectors, and a click
on it or anything inside it still counts but carries no text, id, classes or link. Inputs,
textareas, selects and any password, email or tel field never carry content, whatever the
options say. A selector that does not parse is skipped and reported to onError once.
The query is dropped from those addresses, but a visit's campaign is kept on purpose. The
landing address's utm_source, utm_medium, utm_campaign, utm_term and utm_content, and
the ad networks' click ids (gclid, gbraid, wbraid, fbclid, msclkid, ttclid,
li_fat_id, twclid), are read when a session starts and carried on every event of that
session, with the page that referred it as $session_referrer. The first event a visitor ever
sends also sets their first touch once on the person, as $initial_utm_*, $initial_<click id>
and $initial_referrer ($direct when nothing referred them). In cookieless mode nothing is
kept: each event carries only the campaign of the address it was sent from.
Autocapture also sends a page's Core Web Vitals once per page load as $web_vitals, the first
time the page leaves the visitor's sight: $lcp_ms, $fcp_ms, $cls, $inp_ms and $ttfb_ms,
each only when the browser measured it, with the page's $pathname. Pass
autocaptureOptions: { webVitals: false } to stop it.
A click is recorded against the button, link or control it landed on, so a press on the icon
inside a button is a click on the button. Describe what the person is trying to do with
data-prodantix, and the click carries it as $el_description:
<button data-prodantix="Upgrade to Pro" data-prodantix-action="upgrade_plan">Upgrade</button>The value is trimmed, an empty one counts as absent, and one over 300 characters is ignored
whole and reported to onError once, never cut short. data-prodantix-action is an optional
stable identifier, recorded as $el_action. Without an annotation the description is inferred:
the accessible label or visible text when captureElementText is on, then a link's destination,
then the element's role or tag, and $el_description_source says which. The annotation is read
from the clicked element or the interactive element around it, never from a plain container.
data-prodantix-ignore on an element or any of its ancestors stops its clicks from being sent at
all. A manual event reads the same two attributes when it names its element:
client.capture('Plan upgraded', { element: event.currentTarget }). Never put a name, an email
address, an account id or anything else personal in an annotation.
A session id is minted per
visit (thirty minutes idle, twenty-four hours at most) and stamped on every event; pass
sessionTracking: false to stop it.
A cookie cannot cross a registrable domain, so a visitor who follows a link
from example.com to example-app.com would be two visitors. Pass
linkedDomains: ['example.com', 'example-app.com'] (empty by default) and the
client decorates outbound links to those domains, on click and auxclick, with a
_pdx parameter carrying the anonymous id, the session id and the moment the
session started, so the session window continues across the hop. Only the
anonymous id travels, never an identified one: the destination identifies the
person itself. Same-domain links, links already carrying _pdx, and mailto:,
tel:, javascript: and hash links are left alone. On arrival createWebClient
adopts _pdx before identity is built and strips it with history.replaceState,
so it never appears in $current_url; an id this host already held is folded in
with $create_alias, and a host that has already identified a person keeps that
person.
The visitor's own answer about that join rides the same shared store, under
pdx.<namespace>.consent, so every subdomain and a server reading the cookie
through readSharedIdentity see the one answer. Record it with
prodantix.setConsent({ identityLink: false }), read it back with
prodantix.consent(), and pass consent to createWebClient when your app
already holds the answer (a consent banner is yours to build, and prodantix
honours what it collects). While identityLink is false, identify sends no
anonymous id to join to the person, and a link to a linkedDomains domain is
left undecorated, since carrying the id across is the same join by another
route. Unset or true allows both, subject to the project's own setting.
Changing the answer takes effect on the next identify and the next click:
nothing already joined is unjoined.
Node / server
import { createNodeClient } from '@prodantix/sdk/node'
const prodantix = createNodeClient({
apiKey: process.env.PRODANTIX_PUBLIC_KEY,
host: 'https://eu.api.prodantix.com',
})
prodantix.capture('job.completed', { properties: { queue: 'emails' } })
await prodantix.shutdown() // flush before exitCore
ProdantixClient (exported from the package root) is the runtime-agnostic core. The web
and node entrypoints are thin wrappers that inject the right storage, transport, and
lifecycle hooks. Provide your own storage, transport, clock, or ids to run it
anywhere.
API
| Method | Purpose |
| --- | --- |
| capture(name, { properties?, sessionId?, timestamp? }) | Record an event. Names are lowercase-dotted (order.completed). |
| identify(distinctId, { set? }) | Bind the current anonymous identity to a known user; merges history server-side. |
| alias(alias) | Link an additional id to the current user. |
| group(type, key, properties?) | Associate the user with a group. |
| setPersonProperties(set?, setOnce?) | Update person properties. |
| isFeatureEnabled(key) | Evaluate a feature flag for the current user (async). |
| getAllFlags() | Fetch every flag for the current user. |
| getCachedFlag(key) | Read the last-fetched flag value synchronously. |
| flush() | Send queued events now. |
| reset() | Clear identity (e.g. on logout). |
| shutdown() | Stop the flush timer and flush once. |
Configuration
| Option | Default | Notes |
| --- | --- | --- |
| apiKey | required | Public project key (pdx_pub_…). Required. |
| host | required | Ingest base URL. Required. |
| flagsHost | host | Flag-eval base URL (GET /v1/flags). |
| flushAt | 20 | Flush when this many events are queued. |
| flushIntervalMs | 10000 | Periodic flush interval; 0 disables the timer. |
| maxQueueSize | 1000 | Bounded queue; oldest events are dropped past this. |
| maxRetries | 3 | Transport retries (exponential backoff; 4xx fail fast). |
| requestTimeoutMs | 10000 | Per-request timeout. |
| defaultProperties | {} | Object or factory merged into every event. |
| onError | no-op | Delivery/validation error hook. |
Events are queued in memory (and persisted to storage where available), batched, and
delivered with retry + exponential backoff. Delivery never throws into your application;
failures surface through onError and the batch is retried on the next flush.
