SDK Setup

TrackStack SDK is designed for clean app code:

• one initialization point
• one canonical capture API
• one shared queue for high-volume pages
• optional destination overrides only when needed

Recommended initialization

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",
  },
});

Canonical event contract

Use canonical fields first. Only use platformParams for explicit destination overrides.

trackstack.capture("Purchase", {
  eventId: "evt_123",
  email: "jane@example.com",
  value: 1299,
  currency: "USD",
  transactionId: "txn_123",
  platformParams: {
    meta: { content_type: "saas", content_name: "Growth plan" },
    linkedin: {
      conversionRuleId: "signup_converted",
      conversionValue: { amount: "99.00", currencyCode: "USD" }
    },
    tiktok: { event_source_id: "tt_01", contents: [{ id: "plan_pro", quantity: 1 }] }
  }
});

React + Next.js pattern

import { TrackStackPageview, TrackStackProvider } from "@trackstack/sdk";
import { trackstack } from "@/lib/trackstack";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TrackStackProvider instance={trackstack}>
      <TrackStackPageview />
      {children}
    </TrackStackProvider>
  );
}

Init and queue behavior

• trackstack.init() is safe to call more than once (provider + direct calls).
• If you call capture() before init finishes, events are queued and flushed after init settles.
• The SDK batches edge delivery (/events) up to 100 events per request, so pages with many interactions do not fire one network request per event.
• You can pass eventId to capture() when you need deterministic dedup with external systems; otherwise TrackStack generates one automatically.

trackstack.capture("FeatureUsed", {
  eventId: "evt_feature_click_001",
  email: "jane@example.com",
  feature: "onboarding-checklist",
});

Operational guidance

• Prefer server-side capture for critical revenue events.
• Keep eventId stable across retries when you provide one.
• Configure destination credentials in dashboard settings, not client code.

CAPI support and data handling

TrackStack SDK sends canonical event fields to your TrackStack edge endpoint over HTTPS. The edge layer applies destination-specific transforms and privacy-safe handling before CAPI delivery.

What to send from your app

Provide canonical identifiers and event metadata when available:

• email, phone
• firstName, lastName
• city, state, zip, country
• externalId
• eventId (recommended for dedup parity)

Do not pre-hash identifiers in app code.

What TrackStack supports

Provider	Identity matching support	Dedup support	Notes
Meta	Advanced match fields + request context	Yes (eventId)	Optimized for Pixel + CAPI parity.
Google	Measurement Protocol user matching	Yes (transaction_id/event correlation)	Supports GA4-compatible server payloads.
LinkedIn	Conversions API user matching	Yes (eventId)	Supports conversion rule routing and optional first-party click identifiers.
TikTok	Events API matching parameters	Yes (eventId)	Supports server + pixel dedup patterns.
X	Conversion API identifiers	Yes (conversion_id parity)	Supports hashed identifier routing where configured.
Reddit	Conversions API identity payloads	Yes	Supports standard conversion delivery patterns.
Quora	Conversions API identity payloads	Yes	Supports lead and purchase signal routing.

Design principle

• Keep product code destination-agnostic.
• Keep destination credentials and matching logic out of app code.
• Keep identity handling centralized at the edge for consistency and maintainability.

Developer checklist

• Initialize once in a shared module.
• Use canonical event names across your app.
• Keep platform-specific logic out of product components.
• Validate payloads in API playground before launch.