A-Track Node SDK

Analytics SDK for Node.js services and SSR backends.

Features

• initialization with a publicKey
• automatic uuid generation when one is not provided
• support for your own uuid during initialization
• user attribute create/update flow
• user event delivery
• memory storage by default, with pluggable storage support
• Node.js-friendly request context helpers

Geo-based API routing

The SDK sends requests to:

• https://api.a-track.io by default
• https://<geo>.api.a-track.io when geo is provided

Authentication/project routing header:

• x-a-track-key: <publicKey>

Default endpoints:

• /init
• /attributes
• /event

Available geo values:

• nyc
• sfo
• ams
• sgp
• lon
• fra
• tor
• blr
• syd
• atl
• ric

Basic usage

import { createATrackNodeSdk } from "@a-track/node-sdk";

const sdk = createATrackNodeSdk({
  publicKey: "pub_xxxxx",
  geo: "fra",
});

await sdk.init({
  user: {
    uuid: "server-user-42",
  },
});

await sdk.track({
  event: "order_created",
  attributes: {
    orderId: "ord_123",
    total: 149,
  },
});

Generated uuid and later tracking

You can initialize without passing a user uuid, let the SDK generate one, and then read it back:

const result = await sdk.init();
const uuidFromInit = result.uuid;
const currentUser = sdk.getUser();
const sameUuid = currentUser?.uuid;

Later, anywhere else in your code, you can track an event with that explicit uuid:

await sdk.track({
  uuid: uuidFromInit,
  event: "job_processed",
  attributes: {
    source: "worker",
  },
});

Building init payload from request data

import { buildNodeInitPayload, createATrackNodeSdk } from "@a-track/node-sdk";

const sdk = createATrackNodeSdk({
  publicKey: "pub_xxxxx",
});

await sdk.init(buildNodeInitPayload({
  url: "/pricing?source=google",
  referer: "https://google.com",
  ipAddress: "134.122.17.144",
  userAgent: req.headers["user-agent"],
  locale: "en-US",
  timezone: "America/New_York",
  uuid: "crm-user-42",
  userAttributes: {
    plan: "pro",
  },
}));

Updating user attributes

Merge:

await sdk.setAttributes({
  plan: "business",
  seats: 12,
});

Replace:

await sdk.setAttributes(
  {
    plan: "free",
  },
  { replace: true },
);

setAttributes() sends data to /attributes.

Attributes can also be included during init() if you want to initialize the user and attach attributes in the same call.

You can also read the current initialized user at any time:

const currentUser = sdk.getUser();

Events

await sdk.track({
  event: "invoice_paid",
  attributes: {
    invoiceId: "inv_123",
    amount: 499,
  },
});

The SDK sends at least:

• sdkVersion
• uuid
• event
• attributes
• timestamp
• context

Suggested backend contract

POST /init

{
  "sdkVersion": "0.1.0",
  "uuid": "0d54...",
  "isNewUser": true,
  "mode": "merge",
  "context": {},
  "attributes": {},
  "profile": {}
}

POST /attributes

{
  "sdkVersion": "0.1.0",
  "uuid": "0d54...",
  "mode": "merge",
  "attributes": {
    "plan": "business"
  },
  "profile": {}
}

POST /event

{
  "sdkVersion": "0.1.0",
  "uuid": "0d54...",
  "event": "invoice_paid",
  "attributes": {},
  "timestamp": "2026-04-08T12:00:00.000Z",
  "context": {}
}

Header example:

x-a-track-key: pub_xxxxx