Node.js server SDK

@traqio/node is the Traqio SDK for Node.js backends — the server half of Traqio's web SDK. The conversion that counts on a website — a sign-up, a subscription, a purchase — happens on your backend, where the user id is known. This package reports it with the trackID, the ad click id that @traqio/web kept in first-party storage since the landing page, and Traqio credits the campaign that brought the user — deterministically, by that click's id, never by a guess. No dependency; Express, Next.js, NestJS, Fastify or plain node:http.

Requirements#

• Node.js 18 or later (the SDK uses the built-in fetch). ESM and CommonJS, with TypeScript types.
• A server key for the product (tq_sk_…). Neither the app's SDK key nor a web key works here.
• @traqio/web on the site, and ads pointing at tracking links with a website destination — that is how the trackID reaches your sign-up form.

Set up#

1. Create a server key#

   In the console, open Integrations → SDK and create a server key. It is shown once: put it in the backend's environment, never in code or in a page. Traqio keeps only a fingerprint of it; a lost key is replaced by a new one, and the old one revoked.

   .env

   TRAQIO_SECRET_KEY=tq_sk_...

2. Install the package#

   npm install @traqio/node

3. Create the client#

   import { Traqio } from "@traqio/node";
   
   // One client per process. The key comes from the server's environment, never from code.
   export const traqio = new Traqio({ secretKey: process.env.TRAQIO_SECRET_KEY! });

   The client holds no connection: one per process is enough. It refuses a web key (tq_web_…) and refuses to start in a browser.

4. Report the sign-up with its trackID#

   Call signup() once, where the account is created. @traqio/web writes the trackID in the traq_click cookie on your own domain, so the browser sends it with the sign-up request:

   ExpressNext.jsNestJS

   import { trackIdFromRequest } from "@traqio/node";
   import { traqio } from "./traqio";
   
   app.post("/signup", async (req, res) => {
     const user = await users.create(req.body);
   
     // The trackID arrives with the request: @traqio/web set the traq_click cookie.
     const result = await traqio
       .signup({ userId: user.id, trackId: trackIdFromRequest(req) })
       .catch((err) => logger.warn(err)); // never fail the sign-up itself
   
     res.status(201).json(user);
   });

   If the backend is on another domain than the site, the cookie does not reach it: send Traqio.getTrackId() from the browser with the form instead. The sign-up is the moment the user is acquired; the last click before it, inside your attribution window, gets the credit.

5. Track the conversions#

   await traqio.track({
     userId: user.id,
     name: "purchase",
     value: 49,
     currency: "EUR",
     transactionId: paymentIntent.id, // one payment, one row — whoever reports it
     store: "stripe",
   });

   Conversions follow the user: they are credited to the campaign that acquired them. Several events can go in one call:

   await traqio.send({
     userId: user.id,
     events: [
       { name: "trial_started" },
       { name: "purchase", value: 49, currency: "EUR", transactionId: invoice.id, store: "stripe" },
     ],
   });

What the response tells you#

const result = await traqio.signup({ userId: user.id, trackId });

result.trackId;     // "matched" | "unknown" | "expired" | "claimed" | "refused" (absent without a trackID)
result.acquired;    // true: the sign-up is recorded
result.attribution; // { type: "deterministic", network: "meta", campaignId: "…", adsetId, adId }

What it does today, and what it does not#

Conversions sent here appear in Live events, marked as not matched to an install — expected for a website. A sign-up credited to a campaign is counted in the ROAS report as a web conversion of that campaign, beside its installs, and the response of each call gives you the attribution at once.

Errors and retries#

A network error, a timeout, a 429 or a 5xx is retried — twice by default, with the same body, so nothing is counted twice. A 4xx (wrong or revoked key, invalid payload) is not retried. Both end as a TraqioError:

import { TraqioError } from "@traqio/node";

try {
  await traqio.signup({ userId: user.id, trackId });
} catch (err) {
  if (err instanceof TraqioError) {
    // err.status: 401 = wrong or revoked key, 400 = invalid payload, undefined = network
    logger.warn({ status: err.status, body: err.body }, err.message);
  }
}

API reference#

interface TraqioOptions {
  secretKey: string;     // the server key, tq_sk_… — required
  endpoint?: string;     // default "https://api.traqio.app"
  timeoutMs?: number;    // per attempt — default 10000
  maxRetries?: number;   // after a network error, a 429 or a 5xx — default 2
  fetch?: typeof fetch;  // a custom fetch (proxies, tests)
}

Frequently asked questions#

Why does a server SDK need its own key?

Because it is the only one allowed to tie a conversion to an ad click. The web key of @traqio/web sits in your page where anyone can read it, so it can never attribute anything; the server key stays on your backend, is sent as an Authorization header and is stored by Traqio only as a fingerprint.

Can I use @traqio/node in the browser?

No. It refuses to start when it finds a browser document, and it refuses a web key. In the browser, use @traqio/web, which keeps the trackID until the sign-up request carries it to your backend.

What if the visitor did not come from an ad?

Pass a null trackId, or none. The sign-up is still recorded, and the user is organic: no campaign is credited.

Will a retry count a purchase twice?

No. Each call mints its event ids once and retries the identical body, and a purchase is also keyed on its transactionId, so the same payment reported twice is stored once.