Install

Node and server

TugClient for backend code: track, identify, serve decisions and report outcomes.

Install#

Use tug-sdk from backend code: cron jobs, request handlers, workers. It needs Node 18 or newer and is an ES module, so use import in a .mjs file or a package with "type": "module".

Shell

npm install tug-sdk

Create a client#

TypeScript

import { TugClient } from "tug-sdk";

const tug = new TugClient({
  publicKey: process.env.TUG_PUBLIC_KEY,
  baseUrl: "https://tughq.com/api/v1",
  apiKey: process.env.TUG_API_KEY, // optional server API key
});

baseUrl is optional and defaults to https://tughq.com/api/v1. apiKey is a server API key: with it, calls skip the Allowed origin check and identity verification.

Track and identify#

Unlike the browser script, every Node call names the user: track(distinctId, name, properties) and identify(distinctId, traits). track takes { idempotencyKey, occurredAt } as a fourth argument.

TypeScript

await tug.track("user_123", "invoice_paid", { amount_cents: 9900 });
await tug.identify("user_123", { plan: "pro" });

// Backfill or retry safely: same idempotencyKey, counted once
await tug.track("user_123", "invoice_paid", {}, {
  idempotencyKey: "invoice_8812",
  occurredAt: "2026-11-01T09:30:00Z",
});

Serve a decision#

If the server renders the message right away, count it in the same call:

TypeScript

// Rendering now, on the server: count the serve in the same call (needs apiKey).
const decision = await tug.getDecision({ surface: "banner", userId: "user_123", shown: true });

if (decision) {
  // …render it, then report what the user did:
  await tug.feedback({ distinctId: "user_123", logId: decision.logId, action: "clicked" });
}

If a page renders it later, fetch a placement now and report it when the slot is on screen:

TypeScript

// For a page that renders later: fetch now (free)…
const placement = await tug.getPlacement({ surface: "banner", userId: "user_123" });

// …and report once the slot is on screen. Counts holdout users too.
await tug.reportShown(placement);

getDecision and getPlacement resolve with null when there is nothing to show: no approved message, the user is held back or capped, userId is empty, or the call failed. feedback takes decision.logId as returned (a number, or null).

Without an apiKey, pass userHash to the client or per call when the project requires identity verification.

When a call fails#

No method throws or rejects because of Tug. A refused request or a network failure logs one [tug] warning per distinct reason, and the call resolves (getDecision with null). A fire-and-forget tug.track()in a request handler can't become an unhandled rejection.

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides