Quickstart
Get your first event tracked in under 5 minutes.
Get your first event tracked in under 5 minutes.
Prerequisites
- An account at app.trichidata.com
- A project created inside your workspace
Step 1 — Get your API key
- Open your project in the dashboard
- Go to Settings
- Copy the value of the API key field (
prj_ak_...)
Step 2 — Choose your SDK
Pick the package that matches your environment:
| Environment | Package |
|---|---|
| Browser (vanilla JS, Vue, Svelte, …) | @trichidata/browser |
| React app | @trichidata/react |
| React Native app | @trichidata/react-native |
| Node.js server | @trichidata/node |
| Any environment without an SDK | REST API |
# Browser
npm install @trichidata/browser
# React
npm install @trichidata/react
# React Native (AsyncStorage is a required peer)
npm install @trichidata/react-native @react-native-async-storage/async-storage
# Node.js
npm install @trichidata/nodePrefer to let your AI assistant do this? See Install with your AI assistant.
How sessions work
Every SDK follows the same flow:
init_sdk— authenticate with your API key. The server creates a session. Browser SDKs keep thesdk_sessioncookie and also send the session id in theX-TrichiData-Sessionheader (new in 0.6.0, works with Safari ITP).identify(optional) — associateuserIdand/orappVersionwith the session. At least one field is required; omitted values default to"anonymous"and"unknown"in events.- Track events — use typed helpers (
page,productViewed, …) ortrackCustom.
What SDK 0.6.0 adds
- Anonymous id and sessions — a persistent
anonymousIdand aclientSessionId(new after 30 minutes of inactivity) are attached to every event. When you callidentify, earlier anonymous activity is linked to the user. - Queue and retry — track methods return
{ eventId }immediately. Events are sent in batches (every 5 s or 20 events) with exponential backoff. Callawait client.flush()to send now. - Automatic pageviews (browser and React) —
pageis tracked on init and on every SPA navigation. If you already callclient.page()on each route change, setautoPageviews: falseto avoid duplicates. - Automatic attribution (browser and React) — UTM parameters, click ids (
gclid,gbraid,wbraid,fbclid,ttclid,msclkid), referrer and landing page are captured with no code. - Consent —
requireConsent: truesends nothing untilclient.setConsent({ analytics: true }). - Logout — call
await client.reset()to start a new anonymous identity.
The API attaches user_id, session_id, and project_id server-side — you do not send them in the event body. Event field names, schemas, and property limits are in the REST API.
Step 3 — Initialize
React
Wrap your app with TrichiDataProvider. It creates a TrichiDataClient, calls init_sdk automatically, and stores the sdk_session cookie in the browser.
import { TrichiDataProvider } from '@trichidata/react';
function App() {
return (
<TrichiDataProvider apiKey="prj_ak_xxxxxxxxxxxx">
<YourApp />
</TrichiDataProvider>
);
}Browser
import { TrichiDataClient } from '@trichidata/browser';
const client = new TrichiDataClient({ apiKey: 'prj_ak_xxxxxxxxxxxx' });
await client.init();Node.js
import { TrichiDataClient } from '@trichidata/node';
const client = new TrichiDataClient({
apiKey: 'prj_ak_xxxxxxxxxxxx',
});
await client.init({
device: {
ip: '203.0.113.42',
userAgent: 'MyService/1.0 (Node)',
locale: 'en-US',
timezone: 'UTC',
},
});The client calls POST /api/v1/init_sdk against https://sdk-api.trichidata.com.
Step 4 — Identify a user (optional)
await client.identify({ userId: 'usr_7f3a9b2c', appVersion: '2.4.1' });In React, get the client from context:
import { useTrichiData } from '@trichidata/react';
function Profile() {
const client = useTrichiData();
const handleLogin = () => {
void client.identify({ userId: 'usr_7f3a9b2c', appVersion: '2.4.1' });
};
return <button onClick={handleLogin}>Log in</button>;
}Step 5 — Send your first event
await client.page({
url: 'https://example.com/',
title: 'Home',
});Or a custom event:
await client.trackCustom('promo_banner_click', { slot: 'hero' });With SDK 0.6.0 the browser and React SDKs already send a page event on init, so you can skip this step there.
That's it. Open Live events in your project — you should see the event within a few seconds.
Step 6 — Reset on logout
await client.reset();What's next
- Install with your AI assistant — let Cursor or Claude Code do the setup
- Stripe integration — payment events linked to your users
- Browser SDK — vanilla JS and frameworks
- React SDK — Provider and hooks
- React Native SDK — mobile apps
- Node SDK — server-side tracking
- REST API — event types, property schemas, and HTTP reference
- Table Builder — build reports from your event data
- Destinations — forward events to GA4 or Facebook Pixel