Docs

npm package

npm install https://api.3x.example/v1/sdk/3x-engine-sdk-0.1.0.tgz

The package is not on the npm registry yet. Every 3x API serves the SDK it was built with as an npm tarball at /v1/sdk/3x-engine-sdk-<version>.tgz – replace https://api.3x.example with your API origin (the dashboard's install page and Claude's setup_get_instructions fill it in). npm records the URL in package.json and the tarball's integrity in the lockfile, so npm ci stays reproducible; to upgrade, install the URL with the new version. Imports are the same as for a registry install (@3x-engine/sdk, @3x-engine/sdk/next, …).

import { init, track } from "@3x-engine/sdk";

init({ key: "pk_3x_YOUR_PUBLISHABLE_KEY", host: "https://api.3x.example" });

track("newsletter_signup", { list: "weekly" });

Call init once, as early as possible on the client (for example in src/main.tsx before rendering). It is idempotent: a second call behaves like a SPA navigation, never a second tracker. On the server (SSR) every function is a no-op.

Entry points

ImportContents
@3x-engine/sdkinit, track, goal, funnelStep, page, identify, conversion, consent, flush, getIds, optOut, optIn, the preset helpers, and the x3 object
@3x-engine/sdk/pluginsvideo(), sections(), forms() – tree-shakeable plugins
@3x-engine/sdk/presetsCPI drop-in bridges and consent adapters
@3x-engine/sdk/react<X3Provider>, useX3() (React)
@3x-engine/sdk/next<X3Analytics>, fetchClientConfig() (Next.js)
@3x-engine/sdk/next/proxycreateX3ProxyHandler() for the first-party proxy (Proxy for Next.js)
@3x-engine/sdk/servercreateX3Server(), requestContext() – Node/edge helper with a secret key (Server helper)
@3x-engine/sdk/pixelDOM-free transport for Shopify web pixels (Shopify)

ESM and CommonJS builds are shipped for the core, /server, /next/proxy, /presets and /plugins; /react and /next are ESM with "use client" preserved. Types are bundled.

Plugins

The npm core does not include the video, sections and forms plugins – install the ones you need:

import { init } from "@3x-engine/sdk";
import { forms, sections, video } from "@3x-engine/sdk/plugins";

init({ key: "pk_3x_…", host: "/n3", plugins: [video(), sections(), forms()] });

identify(), consent adapters and booking adapters are loaded lazily when used or configured.

Options

init({
  key: "pk_3x_…",          // publishable key (required)
  host: "/n3",             // API origin or proxy path; default "/n3" (the first-party proxy) – set the API origin if you have no proxy
  config: clientConfig,    // inline client config (skips GET /v1/c/{pk})
  consent: "pending",      // initial consent; default: read from the consent key / CMP adapters
  autocapture: { pageviews: true, clicks: true, scroll: true, engagement: true, forms: true, video: true, sections: true },
  plugins: [],             // ESM plugins
  hashRouting: false,      // #/route changes are pageviews
  test: false,             // mark this page load as test traffic
  debug: false,            // window.__x3 + console diagnostics
});

The complete API with every method is in the SDK reference.

Script tag or npm?

Both have the same behaviour. Prefer npm when you have a bundler and want types and tree-shaking; prefer the script tag when you cannot add dependencies or want the tracker updated without a deploy. Do not use both on the same page.