See what your server did for each user

Backend SDK

Three steps

1. 01

   Create a server key

   In Settings, open Projects, then your project, then "Sources & keys". On the "Server keys" card, press "Create a server key". Give the key a label. Sequential shows the key once. Store it in your secret manager. It is not the write key. Never put it in a web page.

2. 02

   Install the SDK

   The package is @usesequential/node. It has no dependencies, it needs Node 18 or later, and it works with CommonJS and ES modules. Types are included. Licence: MIT.

3. 03

   Send events with the user id

   Call track() with the event name and your user id. To join the browser session too, pass the request: the browser SDK writes a small first-party cookie, and contextFromRequest() reads it.

npm install @usesequential/node

import { SequentialServer, contextFromRequest } from '@usesequential/node';

const sequential = new SequentialServer({ secretKey: process.env.SEQUENTIAL_SERVER_KEY });

app.post('/api/checkout', async (req, res) => {
  // ... your code
  sequential.track({ event: 'payment_captured', userId: req.user.id, context: contextFromRequest(req) });
  res.sendStatus(204);
});

One person, one timeline

The user id decides the person. The context adds the session. When Sequential can prove that the context belongs to that user, the event goes into that browser session, next to the replay. When it cannot, Sequential keeps the event on the user, leaves the session out and counts it as "context dropped". So a forged cookie cannot put an event into another person’s session.

With no user id, the context alone decides: the event goes on that visitor and that session. When the visitor signs in later, the event shows on the user.

On the user page, the "Backend activity" strip lists the events your server sent, newest first. Each row has the event name and the time. A row that has a session links to its replay. Your coding agent sees the same list in get_user_journey, as names and times.

Server errors become findings

Call captureError(err) in your error handler, or captureHttpError() for a 5xx answer. Sequential stores the error type, the message and the first 20 lines of the stack.

• At once. An error from your server opens a finding at its first occurrence.
• Marked. A finding with server occurrences has a "Server" chip. When all of them came from your server, the page row reads "From your server".
• Counted honestly. An error with no browser session counts in people and occurrences, never in sessions.
• Joined. A server error and a browser error with no page, of the same type and message, are one finding.
• For your agent. list_errors gives each group its source: browser, server or both. Findings carry the same sources.

An SDK that does not get in the way

• track() never throws. It returns true or false.
• Events go out in batches: every 100 events or every second.
• A failed batch is tried again up to 3 times, with backoff. A 429 waits for Retry-After. A retried batch is stored once.
• Each drop has a reason in stats and in onError: invalid event, no identity, queue full, too large, refused, retries used up.
• The timer never keeps your process alive. In serverless code, call await flush() before you return.
• disabled: true sends nothing, for tests and local runs.

What server events count as

Server events are not page views, sessions, users or visitors. Plans count sessions, and a server event never starts one. So server events do not add to your billed usage.

Sequential stores no browser, device, IP address, country or URL for a server event. A server event never identifies a person.

Funnels, flows and event search count server events, so "paid" can be a step after "clicked Pay".

Server keys

• Stored as a hash. Sequential keeps the SHA-256 and the last 4 characters. The list shows the label, the last 4 and when each key was last used.
• Revoke any time. Servers that send with a revoked key are refused within seconds. To rotate a key, create a new key, deploy it, then revoke the old one.
• Owners and admins. They create and revoke keys. With two-factor on, creating a key asks for a code. Members see the list.
• Not for browsers. A request that carries an Origin header is refused. The server key also does not work on the browser route.

Good to know

• Node only. There is no SDK for other server languages yet.
• No identify from the server. Link ids in the browser.
• The cookie is an analytics cookie. List __sq_ctx with your analytics cookies. It is first party, lasts 30 minutes and is set only while the browser SDK records. Opt-out clears it. For a signed-in visitor it can carry your user id.
• Across sites or from an app. The cookie stays on your domain. From another site or a native app, send the x-sequential-context header.
• Right after sign-in. In about the first minute after your page identifies a visitor, a server event stays on the user but may not join the session yet.
• Several tabs. Each tab has its own session and the cookie is shared, so the tab that wrote last wins.
• Limits. 50 requests a second per key, 500 events and 1 MB per request. Your project’s event rate limit applies too.
• Trial projects. A trial project cannot have server keys. Claim the project first.
• Personal data. Error messages are stored as sent. Keep personal data out of them.

Questions engineers ask