Skip to content
Docs menu Servers

Node.js

Send purchases, refunds and sign-ups from your backend, with the customer's IP, user agent and click IDs taken from their request

On this page

Requires Node.js 20 or newer. Works with ESM and CommonJS.

Install#

Shell
npm install @sfere.io/sfere-node

Send an event#

Use a server key and keep it in an environment variable.

server.jsJavaScript
import { SfereAnalytics, requestContext } from "@sfere.io/sfere-node";

const sfere = new SfereAnalytics({
  writeKey: process.env.SFERE_WRITE_KEY,   // server key
  host: "https://events.sfere.io",
});

// In a request handler (Express, Fastify, Next.js, plain http, or a Fetch API Request):
sfere.track({
  userId: "user_1234",
  event: "purchase",
  properties: {
    transaction_id: "order_98765",
    currency: "USD",
    value: 313,
    items: [{ item_id: "sku_221", item_name: "Linen Shirt", price: 149, quantity: 1 }],
    sfere_dedup_id: "order_98765",   // the same value as the browser's purchase event, if you send one
  },
  context: requestContext(req),
});

// On shutdown, so queued events are sent:
await sfere.closeAndFlush();

The client has the full analytics API: track, identify, page, screen, group, alias, flush and closeAndFlush.

Why requestContext(req) matters#

A server event comes from your server, not from your customer, so Sfere cannot fill in their IP address or browser. Ad-platform conversion APIs match on exactly those values. requestContext(req) reads them from the customer’s request:

Field Taken from
context.ip The left-most X-Forwarded-For, then X-Real-IP, then the socket address
context.userAgent User-Agent
context.locale The first Accept-Language tag
context.page The request URL (or the pageUrl option) and Referer
context.campaign utm_*, gad_source and gad_campaignid in that URL
context.clientIds Ad cookies such as _fbp, _fbc, _ttp and _gcl_aw, and landing click IDs such as gclid

It accepts a Node IncomingMessage (http, Express, Fastify’s request.raw, Next.js API routes) and a Fetch API Request (Next.js route handlers, Hono, Remix, edge runtimes).

Option Default What it does
trustProxy true Read the IP from forwarding headers. Set false when clients reach the app directly, so they cannot choose the IP they are reported with.
pageUrl The request URL The page the customer is on, when the request is an API call from that page.

For events outside a customer request, such as a webhook, a scheduled job or a refund issued by staff, pass the context you stored from their session, or send the event without one.

Options#

Option Default What it does
writeKey required Server key, keyId:secret.
host required https://events.sfere.io. Events go to /v1/batch.
flushAt 15 Events per request.
flushInterval 10000 Longest an event waits before its batch is sent, in milliseconds.
maxRetries 3 Retries per batch on network errors, 5xx and 429, with backoff.
httpRequestTimeout 10000 Per-request timeout in milliseconds.
disable false Accept calls but send nothing, for tests and local development.