#SDK overview: web and apps

X3 measures websites and native apps with one family of SDKs. They share one model: a session is a visit, a pageview is a page on the web and a screen view in an app, events are attached to a pageview or screen view, identify links a session to a person by hashes, a lead is an explicit inquiry, and purchases become conversions only when a server confirms them. Everything lands in the same project, so a journey can start on your website and end in your app.

All SDKs talk to the X3 API directly or, recommended, through a first-party proxy on your own domain (https://your-domain/n3). Publishable keys (pk_3x_…) are public; secret keys (sk_3x_…) belong on your server only (keys).

The web SDK follows the project's consent mode; the app SDKs make you choose a consent mode in code (always, opt_in or opt_out).

You decide how consent works in your app, and you are responsible for that decision. X3 implements your choice technically but does not check whether it is legally right for your users and countries. Clarify the legal basis with your privacy counsel and describe X3 in your privacy policy and in the App Store and Google Play privacy details.

#Web SDK

@x3growth/sdk is the browser tracker plus adapters, a first-party proxy handler, a server helper and a DOM-free pixel transport. The same API exists in three forms:

• ESM exports: import { init, track } from "@x3growth/sdk" (npm package);
• the x3 object of the script-tag build: x3.track(…) (script tag);
• queue commands before the script has loaded: x3("track", "signup_started", { plan: "pro" }).

Every browser method swallows its own errors; tracking never breaks your page. The detailed behaviour of each method is in the SDK reference.

#Entry points

#Tracker functions

import { init, track, identify, getIds } from "@x3growth/sdk";

init({ key: "pk_3x_YOUR_SITE_KEY", host: "/n3" });
track("plan_selected", { plan: "year" });
await identify({ email: "jane@example.com", form: "newsletter" });
const { sessionId } = getIds(); // send it with your form post

#Server helper

createX3Server({ apiUrl, apiKey, project?, publishableKey?, proxyKey?, timeoutMs?, fetch? }) returns project(), leads.create, leads.addNote, conversions.create, events.track, purchase / purchases.create, refund / purchases.refund, experiments.assign and requestContext. Errors are X3ServerError (RFC 9457 problem). Details: Server helper and shop purchases. App purchases use the same purchase call with the store transaction id (purchases in apps).

#Proxy

import { createX3ProxyHandler } from "@x3growth/sdk/next/proxy";

export const { GET, POST, OPTIONS } = createX3ProxyHandler({
  apiOrigin: process.env.X3_API_ORIGIN!,
  proxyKey: process.env.X3_PROXY_KEY,
});

The handler forwards only X3's path families and adds the visitor's IP, country and the proxy key. From @x3growth/sdk 1.3.0 it also forwards the app paths (/v1/m/*), X3 links (/go/<code>) and, through two extra route files, Apple's postback copies; see postback copies and the proxy protocol.

#App SDKs

The app SDKs are native: Swift for iOS and Kotlin for Android, with thin wrappers for React Native (an Expo Module with a config plugin) and Flutter (a plugin with Pigeon channels). Every behaviour (consent, queue, sessions, hashing, attribution, recordings) lives in the native cores, so all four APIs use the same names and the same rules (architecture).

Start with the app quickstart; every call is described in the app SDK reference.

X3.configure(key: "pk_3x_YOUR_APP_KEY", options: X3Options(consent: X3ConsentOptions(mode: .optIn)))
X3.screen("Paywall")
X3.identify(userId: user.id, email: user.email)
X3.track("plan_selected", properties: ["plan": "year"])

#Function matrix

Rows are concepts, columns the SDKs. "–" means the concept does not exist on that platform.