npm install @togohq/sdk-node
Node 20 or later, zero runtime dependencies. Create one client per process, shared by every
request. Nothing on the client throws: a problem is logged as [togo] … and the event is retried
or dropped. A guide to using it: Node.js and serverless.
init(options)
import { init } from '@togohq/sdk-node';
const analytics = init({ writeKey: process.env.TOGO_WRITE_KEY! });
Options
| Option | Default | What it does |
|---|---|---|
writeKey |
— | Required. togo_pkt_… (test) or togo_pkl_… (live) |
endpoint |
https://in.togohq.ai |
Where events are sent |
batchSize |
100 |
Events per request, 100 to 500 |
flushIntervalSeconds |
10 |
How long an event may wait before it is sent, 10 to 60 seconds |
maxQueueSize |
10000 |
Events held in memory while Togo is unreachable; past it, new events are dropped |
defaultProperties |
— | Properties on every track() event, such as { service: 'billing' } |
A batchSize or flushIntervalSeconds outside its range is moved into it, with a warning in your
logs. To send an event at once, await analytics.flush() after it rather than lowering either.
defaultProperties is fixed when the client is created, because a client shared by every request
must not carry one request’s value onto the next. An event’s own value for the same key wins, and
the SDK logs one error for the collision.
The person argument
Every call names who it is about, with at least one of:
| Field | What it is |
|---|---|
userId |
Your id for the signed-in user — the same one the browser passes to identify() |
anonymousId |
The browser’s anonymous id, forwarded, for a visitor who has not signed in |
sessionId |
Optional. The browser’s session id, forwarded, so the event joins that visit |
An event with neither userId nor anonymousId is dropped with an error. Server events carry no
device, browser or location.
track(eventName, properties, person)
analytics.track('order_paid', { plan: 'pro' }, { userId: user.id });
Returns the event’s eventId, or undefined when nothing was queued — no person named, a refused
name, a malformed write key or one already rejected, after shutdown(), or a full queue. The key
is checked in the background, so a call made before a rejection comes back still returns an id, and
the rejection drops that event. An id means the event was queued, not that it arrived. A test
passes these ids to verify_tracking_by_event_ids
after await analytics.flush().
setPersonProperties(ops, person)
analytics.setPersonProperties({ set: { plan: 'pro' } }, { userId: user.id });
set, setOnce and unset, as in the browser. Takes userId or anonymousId, not sessionId.
Returns the profile write’s eventId, or undefined when nothing was queued — an empty call, no
person named, a malformed or already-rejected write key, after shutdown(), or a full queue.
flush()
await analytics.flush() sends everything queued now. In a serverless function, call it before
you return, because the platform may freeze the process as soon as the response is sent. A send
that fails on the network or with a server error is retried twice within about a second before
flush() resolves.
withFlush(handler)
export const handler = analytics.withFlush(async (event) => {
analytics.track('order_paid', { plan: 'pro' }, { userId: event.userId });
return { statusCode: 200 };
});
Returns your handler wrapped so flush() runs after it finishes — also when it throws. What the
handler returns or throws is passed through unchanged. Use it for every serverless handler, so no
return path can skip the flush.
shutdown()
await analytics.shutdown() sends what is queued and stops the client. Call it on SIGTERM in a
long-running server. A script that exits on its own sends its queue first anyway; shutdown() is
the explicit way to be sure.
Delivery
Events are batched and retried with backoff when the endpoint is unreachable or busy, keeping the same event id across attempts.