Node SDK

Use this guide when tracking events from a Node.js server — API routes, background jobs, webhooks.

For session flow and event schemas, see the REST API. For a guided first integration, see Quickstart.

Installation

npm install @trichidata/node

Requires Node.js >= 18.

Setup

@trichidata/node provides TrichiDataClient configured for server environments. The client parses the session cookie from init_sdk and sends it on subsequent requests — Node.js does not use a browser cookie jar.

import { TrichiDataClient } from '@trichidata/node';

const client = new TrichiDataClient({
  apiKey: process.env.TRICHIDATA_API_KEY!,
});

await client.init({
  device: {
    ip: '203.0.113.42',
    userAgent: 'MyService/1.0 (Node)',
    locale: 'en-US',
    timezone: 'UTC',
  },
  // optional: pass GA/Meta IDs from the incoming request
  tracking: {
    ga4: { clientId: '717831353.1785147356' },
  },
});

await client.identify({ userId: 'usr_7f3a9b2c', appVersion: '2.4.1' });

await client.orderCompleted({
  orderId: 'ord_123',
  total: 49.9,
  currency: 'USD',
  items: [{ productId: 'p1', name: 'Widget', price: 49.9, quantity: 1 }],
});

Node-specific notes

Device info

You must provide device.ip and device.userAgent explicitly in the init() payload. The SDK does not detect them automatically.

Tracking context

Pass tracking when you have GA4 / Meta identifiers from the client request (cookies or known IDs). There is no automatic browser cookie parsing on Node. If omitted, the SDK generates a GA-like clientId and sends an empty metaPixel object so init_sdk validation still passes.

Typical use cases

• API route handlers that track server-side conversions
• Background jobs and cron tasks
• Webhook processors forwarding business events

Client methods

See REST API for reserved eventName values and properties schemas.

See also

• Quickstart — track your first event
• REST API — event schemas and HTTP reference