Truxl
docs / getting started / quickstart

Quickstart

Send your first event to Truxl in under an hour. This guide covers installing the SDK, identifying users, and seeing data flow into your workspace.

  1. 1
    Create a workspace
    Sign up at app.truxl.com, name your workspace, and grab your project key from Settings → API keys. Use a separate key per environment.
  2. 2
    Install the SDK
    Truxl ships SDKs for every major language. Install for your stack and import the client.
  3. 3
    Initialize and send an event
    Identify your user, then track your first event. You'll see it appear in Live Stream within a few seconds.

Install the SDK

Truxl's JavaScript SDK is a lightweight (~8 KB), zero-dependency browser library. Install it from npm for bundlers like Vite or Webpack, or drop in the CDN script tag — see the JavaScript SDK below.

npm
npm install @truxl/javascript-sdk
# or
yarn add @truxl/javascript-sdk
pnpm add @truxl/javascript-sdk

Identify your user

Identifying users lets Truxl tie all of a person's events together — across devices and sessions. Call identify once you know who they are.

javascript
import { TruxlClient } from '@truxl/javascript-sdk';

const truxl = new TruxlClient({
  projectToken: 'YOUR_PROJECT_TOKEN',
  clientSecret: 'YOUR_CLIENT_SECRET',
});

truxl.identify(user.id, {
  plan: user.plan,
  signed_up_at: user.createdAt,
});
Tip. Use a stable, server-issued id (database PK or UUID) — not the user's email — so user identity survives email changes and works on the server.

Your first event

Tracking an event is one call. Truxl auto-captures pageviews, clicks, and form submits — you only write code for events that are specific to your product.

javascript
truxl.track('checkout_completed', {
  plan: 'pro',
  mrr: 29,
  source: 'pricing_page',
});

Open Live Stream in your workspace; you should see the event in a few seconds. From here, build your first funnel, set up a retention chart, or ask Truxl in plain English what your activation rate is.

Configuration

projectToken and clientSecret are required; everything else is optional. The defaults batch events and auto-track pageviews out of the box.

javascript
const truxl = new TruxlClient({
  // Required
  projectToken: 'YOUR_PROJECT_TOKEN',
  clientSecret: 'YOUR_CLIENT_SECRET',

  // Optional
  apiEndpoint: 'https://ingestion.api.truxl.com', // default: stage ingestion
  batchSize: 20,            // events per batch before auto-flush
  flushInterval: 5000,      // auto-flush interval (ms)
  maxQueueSize: 10000,      // max queued events
  retryAttempts: 5,         // retries for failed requests
  retryBaseDelay: 1000,     // base backoff delay (ms)
  transport: 'http',        // 'http' | 'websocket'
  track_pageview: true,     // auto-track pageviews
  autocapture: false,       // see Autocapture below
  debug: false,             // log events + config to console
});

Core API

The core API is the same everywhere — track, identify, reset, flush, and destroy.

track(eventName, properties?)
Record a custom event with optional properties.
identify(distinctId, properties?)
Link all events to a known user — call after login or signup.
reset()
Clear the user identity on logout; subsequent events are tracked anonymously.
flush()
Force-send all queued events immediately — useful before navigation or page unload.
destroy()
Tear the SDK down: stop autocapture, clear timers, and close the transport.
javascript
// Track a custom event
truxl.track('checkout_completed', {
  plan: 'pro',
  mrr: 29,
  source: 'pricing_page',
});

// Identify a user after login (all later events link to them)
truxl.identify('user-123', {
  email: 'john@example.com',
  plan: 'pro',
});

// Clear identity on logout — later events are anonymous
truxl.reset();

// Force-send queued events (e.g. before navigation)
truxl.flush();

Autocapture

Set autocapture: true to capture clicks, scroll depth, and form submits with no manual instrumentation — or pass an object to choose exactly what to track. Sensitive fields (passwords, card numbers, tokens) are redacted automatically, and element text is off by default.

javascript
const truxl = new TruxlClient({
  projectToken: 'YOUR_PROJECT_TOKEN',
  clientSecret: 'YOUR_CLIENT_SECRET',
  autocapture: {
    pageview: 'path-only',       // 'full-url' | 'path-only' | false
    click: true,                 // button / link clicks
    submit: true,                // form submissions
    scroll: false,               // scroll depth (25/50/75/100%)
    input: false,                // input changes (sensitive fields redacted)
    dead_click: false,           // clicks with no DOM change
    rage_click: false,           // 3+ rapid clicks on one element
    capture_text_content: false, // capture element text (off for privacy)
  },
});

JavaScript SDK

The Truxl JavaScript SDK is a lightweight (~8 KB), zero-dependency browser library for TypeScript and JavaScript: automatic pageview tracking, optional autocapture, event batching with retry, and HMAC-SHA256 request signing.

Version
v0.1.0
Language
TypeScript / JavaScript · ES2017+
Compatibility
Chrome 58+, Firefox 52+, Safari 11+, Edge 79+
Dependencies
No runtime dependencies

Install

Drop in the CDN script tag for a plain HTML page, or install from npm when you build with a bundler like Vite or Webpack.

html — script tag
<script src="https://sdk.truxl.com/javascript/truxl-0.1.0.umd.js"></script>
<script>
  var truxl = new window.truxl.TruxlClient({
    projectToken: 'YOUR_PROJECT_TOKEN',
    clientSecret: 'YOUR_CLIENT_SECRET',
    apiEndpoint: 'https://ingestion.api.truxl.com',
  });

  truxl.track('page_view', { page: '/home' });
</script>
javascript — npm / esm
import { TruxlClient } from '@truxl/javascript-sdk';

const truxl = new TruxlClient({
  projectToken: 'YOUR_PROJECT_TOKEN',
  clientSecret: 'YOUR_CLIENT_SECRET',
  apiEndpoint: 'https://ingestion.api.truxl.com',
});

Data attribute tracking

Add a data-truxl-event attribute to any clickable element to name a click event without writing JavaScript. When autocapture click tracking is enabled, the SDK reads the attribute on click and attaches its value as the $custom_event_name property of the $autocapture_click event.

html
<button data-truxl-event="cta_hero_click" class="btn-primary">
  Get Started
</button>

Clicking the button above fires $autocapture_click with $custom_event_name: "cta_hero_click" alongside the standard element properties ($element_tag, $element_id, $element_classes, and $element_href for links). The SDK walks up to five ancestors from the click target, so the attribute also works on a wrapper around the button or link. This requires autocapture.click to be enabled (see Autocapture); it is a browser-only feature with no equivalent in the native or server SDKs.

React Native SDK

The Truxl React Native SDK brings event tracking to iOS and Android apps. It initializes asynchronously, ships React hooks (TruxlProvider and useTruxl), and handles screen tracking, AppState-aware session management, and pluggable HMAC signing.

Version
v0.2.0
Language
TypeScript
Compatibility
React Native ≥ 0.70 · React ≥ 17 · AsyncStorage ≥ 1.17
Dependencies
react ≥ 17.0.0
react-native ≥ 0.70.0
@react-native-async-storage/async-storage ≥ 1.17.0

Install

npm
npm install @truxl/react-native-sdk

Quick start

typescript
import { TruxlClient, TruxlProvider, useTruxl } from '@truxl/react-native-sdk';

// Initialize (async — call in app startup)
const client = await TruxlClient.init({
  projectToken: 'YOUR_PROJECT_TOKEN',
  clientSecret: 'YOUR_CLIENT_SECRET',
  apiEndpoint: 'https://ingestion.api.truxl.com',
});

// Wrap your app
export default function App() {
  return (
    <TruxlProvider client={client}>
      <MainNavigator />
    </TruxlProvider>
  );
}

// In any component
function HomeScreen() {
  const truxl = useTruxl();
  truxl.track('button_click', { label: 'Buy Now' });
}

Next.js SDK

The Truxl Next.js SDK does client and server tracking in one package. It ships the TruxlProvider / useTruxl hooks, auto-pageview for both the App and Pages Router, a middleware trackRequest helper, session management, and HMAC signing.

Version
v0.1.0
Language
TypeScript
Compatibility
Next.js ≥ 13 (App or Pages Router) · React ≥ 18 · Next.js 13 / 14 / 15
Dependencies
next ≥ 13.0.0
react ≥ 18.0.0

Install

npm
npm install @truxl/nextjs-sdk

Quick start

typescript
// ── Client: wrap your app (app/layout.tsx) ──
'use client';
import { TruxlProvider } from '@truxl/nextjs-sdk/client';

export default function RootLayout({ children }) {
  return (
    <TruxlProvider config={{
      projectToken: 'YOUR_PROJECT_TOKEN',
      apiEndpoint: 'https://ingestion.api.truxl.com',
      trackPageview: true,
    }}>
      {children}
    </TruxlProvider>
  );
}

// ── Client: track from a component ──
'use client';
import { useTruxl } from '@truxl/nextjs-sdk/client';

function CheckoutButton() {
  const { track } = useTruxl();
  return <button onClick={() => track('checkout_started', { cartValue: 49.99 })}>Checkout</button>;
}

// ── Server: init + track (instrumentation.ts / API route) ──
import { initTruxlServer, getTruxlServer } from '@truxl/nextjs-sdk/server';

initTruxlServer({
  projectToken: process.env.TRUXL_PROJECT_TOKEN,
  clientSecret: process.env.TRUXL_CLIENT_SECRET,
});

getTruxlServer().track({
  distinctId: 'user-123',
  eventName: 'order_created',
  properties: { mrr: 49 },
});

Flutter SDK

The Truxl Flutter SDK is a Dart library for iOS and Android apps. It ships track, identify, alias, flush, and reset, persists device & session IDs, tracks app-lifecycle events, batches with retry, and signs requests with HMAC.

Version
v0.1.0
Language
Dart
Compatibility
Flutter ≥ 3.10 / Dart ≥ 3.0 · iOS 12+ · Android API 21+
Dependencies
http ^1.2.0
shared_preferences ^2.2.0
crypto ^3.0.3

Install

flutter cli
flutter pub add truxl

Or add it to your pubspec.yaml:

yaml — pubspec.yaml
truxl: ^0.1.0

Quick start

dart
import 'package:truxl/truxl.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Truxl.init(const TruxlConfig(
    projectToken: 'YOUR_PROJECT_TOKEN',
    clientSecret: 'YOUR_CLIENT_SECRET',
    apiEndpoint: 'https://ingestion.api.truxl.com',
  ));

  runApp(const MyApp());
}

// Anywhere in your app
final truxl = Truxl.instance;
truxl.track('purchase', properties: {'price': 29.99});
truxl.identify('user-123', {'email': 'user@example.com'});

Android SDK

The Truxl Android SDK is a Kotlin library with a singleton API. It persists state in SharedPreferences, tracks app-lifecycle events, flushes network-aware batches, manages sessions, and signs requests with HMAC.

Version
v0.1.0
Language
Kotlin
Compatibility
Android 5.0 (API 21)+ · Kotlin 1.9+ · targetSdk 34
Dependencies
OkHttp 4.12.0
Moshi 1.15.0
AndroidX Lifecycle 2.7.0

Install

gradle
implementation 'com.truxl:sdk-android:0.1.0'

Quick start

kotlin
// Application.onCreate()
Truxl.init(
    context = this,
    config = TruxlConfig.Builder("YOUR_PROJECT_TOKEN", "YOUR_CLIENT_SECRET")
        .apiEndpoint("https://ingestion.api.truxl.com")
        .batchSize(20)
        .flushIntervalMs(5000)
        .build()
)

// Anywhere in your app
Truxl.track("purchase", mapOf("product_id" to "abc", "price" to 29.99))
Truxl.identify("user-123", mapOf("email" to "user@example.com"))

iOS SDK

The Truxl iOS SDK is a Swift library with a singleton API and no external dependencies — it's built on CryptoKit, Network, and URLSession. It persists state in UserDefaults, tracks app-lifecycle events, flushes network-aware batches, manages sessions, and signs requests with HMAC.

Version
v0.1.0
Language
Swift 5.9+
Compatibility
iOS 14+ / macOS 11+ · Swift 5.9+ · Xcode 15+
Dependencies
No external dependencies (CryptoKit, Network, URLSession)

Install

swift — Package.swift
.package(url: "https://github.com/truxl/truxl-ios-sdk.git", from: "0.1.0")

Or in Xcode: File → Add Package Dependencies, then enter https://github.com/truxl/truxl-ios-sdk.git.

Quick start

swift
import TruxlSDK

// AppDelegate or @main App init
Truxl.initialize(
    config: TruxlConfig.Builder(
        projectToken: "YOUR_PROJECT_TOKEN",
        clientSecret: "YOUR_CLIENT_SECRET"
    )
    .apiEndpoint("https://ingestion.api.truxl.com")
    .batchSize(20)
    .flushIntervalMs(5000)
    .build()
)

// Anywhere in your app
Truxl.track("purchase", properties: ["product_id": "abc", "price": 29.99])
Truxl.identify("user-123", traits: ["email": "user@example.com"])

Node.js SDK

The Truxl Node.js SDK is a zero-dependency, server-side library for TypeScript and JavaScript. It uses a non-blocking queue, batches with retry, supports graceful shutdown, ships both CJS and ESM builds, and signs requests with HMAC.

Version
v0.1.0
Language
TypeScript / JavaScript (server)
Compatibility
Node.js ≥ 18 · built-in node:crypto & node:https
Dependencies
No runtime dependencies (zero deps)

Install

npm
npm install @truxl/node-sdk

Quick start

typescript
import { Truxl } from '@truxl/node-sdk';

const truxl = new Truxl({
  projectToken: 'YOUR_PROJECT_TOKEN',
  clientSecret: 'YOUR_CLIENT_SECRET',
  apiEndpoint: 'https://ingestion.api.truxl.com',
});

// Track a server-side event
truxl.track({
  distinctId: 'user-123',
  eventName: 'subscription_renewed',
  properties: { plan: 'pro', mrr: 49 },
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  await truxl.shutdown();
  process.exit(0);
});

Java SDK

The Truxl Java SDK is a zero-dependency, server-side library with a static facade API and builder-pattern config. It uses a thread-safe queue, batches with retry, supports graceful shutdown, and signs requests with HMAC.

Version
v0.1.0
Language
Java 17+ (server)
Compatibility
Java 17+ · java.net.http.HttpClient & javax.crypto.Mac
Dependencies
No runtime dependencies (zero deps)

Install

gradle
implementation 'com.truxl:sdk-java:0.1.0'

Quick start

java
import com.truxl.sdk.Truxl;
import com.truxl.sdk.TruxlConfig;
import java.util.Map;

// Initialize (e.g. in @PostConstruct or main())
Truxl.init(TruxlConfig.builder()
    .projectToken("YOUR_PROJECT_TOKEN")
    .clientSecret("YOUR_CLIENT_SECRET")
    .apiEndpoint("https://ingestion.api.truxl.com")
    .batchSize(20)
    .flushIntervalMs(5000)
    .build());

// Track
Truxl.track("purchase", "user-123", Map.of("plan", "pro", "mrr", 49));

// Identify
Truxl.identify("user-123", Map.of("email", "user@example.com"));

// Graceful shutdown (in @PreDestroy)
Truxl.shutdown();

Python SDK

The Truxl Python SDK is a zero-dependency, server-side library that uses the standard library only. A background thread consumes a batching queue with retry, it supports graceful shutdown and HMAC signing, and it works with Django, Flask, and FastAPI.

Version
v0.1.0
Language
Python 3.8+ (server)
Compatibility
Python ≥ 3.8 · stdlib only (hmac, hashlib, urllib, threading)
Dependencies
No runtime dependencies (stdlib only)

Install

pip
pip install truxl

Quick start

python
from truxl import Truxl

truxl = Truxl(
    project_token="YOUR_PROJECT_TOKEN",
    client_secret="YOUR_CLIENT_SECRET",
    api_endpoint="https://ingestion.api.truxl.com",
)

# Track
truxl.track(
    distinct_id="user-123",
    event_name="purchase",
    properties={"price": 29.99}
)

# Identify
truxl.identify("user-123", traits={"email": "user@example.com"})

# Shutdown (blocks until queue drains)
truxl.shutdown()

Go SDK

The Truxl Go SDK is a zero-dependency, server-side library that uses the standard library only. It runs a goroutine-based queue, batches with retry, is context-aware, supports graceful shutdown, and signs requests with HMAC.

Version
v0.1.0
Language
Go 1.21+ (server)
Compatibility
Go ≥ 1.21 · stdlib only (crypto/hmac, net/http)
Dependencies
No runtime dependencies (zero deps)

Install

go
go get github.com/truxl/truxl/truxl-sdk/go

Quick start

go
import (
    "time"
    truxl "github.com/truxl/truxl/truxl-sdk/go"
)

client := truxl.New(truxl.Config{
    ProjectToken:  "YOUR_PROJECT_TOKEN",
    ClientSecret:  "YOUR_CLIENT_SECRET",
    APIEndpoint:   "https://ingestion.api.truxl.com",
    BatchSize:     20,
    FlushInterval: 5 * time.Second,
})

// Track
client.Track(truxl.Event{
    DistinctID: "user-123",
    EventName:  "purchase",
    Properties: map[string]interface{}{"price": 29.99},
})

// Graceful shutdown
client.Shutdown()

PHP SDK

The Truxl PHP SDK is a server-side library with request-scoped flushing. It uses a cURL transport, batches events, signs requests with HMAC, auto-flushes on request end, and works with Laravel and WordPress.

Version
v0.1.0
Language
PHP 8.0+ (server)
Compatibility
PHP ≥ 8.0 · requires ext-curl & ext-json
Dependencies
ext-curl
ext-json

Install

composer
composer require truxl/sdk

Quick start

php
<?php
use Truxl\Truxl;

$truxl = Truxl::init([
    'project_token' => 'YOUR_PROJECT_TOKEN',
    'client_secret' => 'YOUR_CLIENT_SECRET',
    'api_endpoint'  => 'https://ingestion.api.truxl.com',
]);

// Track
$truxl->track('purchase', 'user-123', ['price' => 29.99]);

// Identify
$truxl->identify('user-123', ['email' => 'user@example.com']);

// Flush (auto-flushes on request end via register_shutdown_function)
$truxl->flush();

Ruby SDK

The Truxl Ruby SDK is a zero-dependency, server-side library that uses the standard library only. It runs a thread-based queue, batches with retry, supports graceful shutdown, signs requests with HMAC, and is Rails compatible.

Version
v0.1.0
Language
Ruby 3.0+ (server)
Compatibility
Ruby ≥ 3.0 · stdlib only (net/http, openssl, securerandom)
Dependencies
No runtime dependencies (stdlib only)

Install

gem
gem install truxl

Quick start

ruby
require 'truxl'

truxl = Truxl::Client.new(
  project_token: 'YOUR_PROJECT_TOKEN',
  client_secret: 'YOUR_CLIENT_SECRET',
  api_endpoint: 'https://ingestion.api.truxl.com',
)

# Track
truxl.track(
  distinct_id: 'user-123',
  event_name: 'purchase',
  properties: { price: 29.99 }
)

# Identify
truxl.identify('user-123', email: 'user@example.com')

# Shutdown (blocks until queue drains)
truxl.shutdown

REST API

Coming soon

A direct REST API is coming soon and not generally available yet. In the meantime, use the SDK provided for your platform — JavaScript, React Native, Next.js, Flutter, Android, iOS, Node.js, Java, Python, Go, PHP, or Ruby.

Self-hosting

Coming soon

Self-hosting Truxl — Helm chart, Docker Compose, updating, and backups — is coming soon and not generally available yet. Get in touch if you'd like early access.