Quickstart

Prerequisites

• TrackStack account and publishable API key from API Keys
• Node.js and pnpm in your app environment

1) Install the SDK

pnpm add @trackstack/sdk

2) Add environment variables

NEXT_PUBLIC_TRACKSTACK_KEY=ts_live_xxx
NEXT_PUBLIC_EDGE_URL=https://edge.gettrackstack.com  # optional
NEXT_PUBLIC_POSTHOG_KEY=phc_xxx # optional

3) Initialize TrackStack

import { createTrackStack } from "@trackstack/sdk";

export const trackstack = createTrackStack({
  publicKey: process.env.NEXT_PUBLIC_TRACKSTACK_KEY!,
  edge: "https://edge.gettrackstack.com",
  posthog: {
    key: process.env.NEXT_PUBLIC_POSTHOG_KEY!,
    host: "/_ph",
  },
});

4) Identify after login (SSO)

After users sign in — including SAML/OIDC enterprise SSO — attach identity before conversion events:

trackstack.identify(user.id, {
  email: user.email,
  firstName: user.firstName,
  lastName: user.lastName,
});

trackstack.capture("SignUp", { email: user.email, eventId: "signup_" + user.id });

See SSO & event capture for provider helpers (Clerk, Auth0, NextAuth, etc.).

5) Capture a conversion

await trackstack.init(); // optional when using TrackStackProvider in React

trackstack.capture("Purchase", {
  eventId: "evt_001",
  email: "jane@example.com",
  value: 1299,
  currency: "USD",
  transactionId: "txn_001",
  plan: "Growth",
});

For pages that emit multiple events quickly, call capture() for each action. The SDK queues and batches edge delivery automatically.

6) Verify delivery

1. Open dashboard delivery views and compare attempted vs delivered.
2. Inspect failed deliveries and DLQ entries.
3. Use API playground to test the same OpenAPI contract used by the edge.

Key handling

• Use only the publishable TrackStack key in app code (NEXT_PUBLIC_TRACKSTACK_KEY).
• Keep destination platform credentials in dashboard settings; TrackStack stores them encrypted server-side.

Next steps

• SDK setup — React/Next.js integration patterns
• SSO & identify — enterprise SSO and B2B match rates
• B2B SaaS events — Standardize event naming across teams
• Supported platforms — Destination-specific behavior and overrides