Events from your server
Send what your server knows, an order paid or a signup completed, and sign who a page says it is.
@chokh/sdk-node needs nothing beyond Node's own library, Node 22 or newer,
and works as an ES module or CommonJS. It is not on npm yet: it is published
with Chokh's first release.
npm install @chokh/sdk-node
Send events
Make a key for the site with the write:events scope, signed in as an admin
of the site, and keep it on the server. The token is shown once, in the
answer:
curl -b jar -X POST https://analytics.example.com/api/sites/my_site/keys \
-H 'content-type: application/json' \
-d '{"name":"Checkout server","scopes":["write:events"]}'
import { createClient } from '@chokh/sdk-node';
const chokh = createClient({
url: process.env.CHOKH_URL ?? '', // https://analytics.example.com
siteId: process.env.CHOKH_SITE ?? '', // my_site
apiKey: process.env.CHOKH_API_KEY ?? '', // a key with write:events, never in a page
});
// Return at once and never throw: the events go in the background.
chokh.identify('u_42', { plan: 'pro' });
chokh.track('u_42', 'order_paid', { value: 1200, path: '/checkout', props: { currency: 'BDT' } });
// Before the process exits, send what is still queued.
await chokh.shutdown();
track and identify return at once and never throw: the events wait in a
queue and go in the background, so analytics is never the reason a request
hangs. Delivery is at least once: a batch the network lost after Chokh stored
it may be sent again.
Pass the browser's visitor id when you know it, and the event joins the visit that person is in the middle of.
Sign an identify
A page can call identify with any id, and a forged one would be one visitor
reading another's history. So a site can refuse an identify that is not
signed, and keep the signing secret on its server:
import { signUserId } from '@chokh/sdk-node';
// On your server, where the page reads its own session: a signature the page
// passes to identify, so nobody can claim to be somebody else.
export function identifySignature(userId: string): string {
return signUserId(process.env.CHOKH_IDENTIFY_SECRET ?? '', 'my_site', userId);
}
The page then passes the signature as the fourth argument:
pa('identify', user.id, { plan: 'pro' }, signature). The secret is shown
once, when the site is made, and again only when it is changed. It never
reaches a browser.
The signature is one line, so a server in any language can make it:
base64url(hmac_sha256(identifySecret, siteId + "\n" + userId))