Skip to Content
TrichiDataTrichiData

Quickstart

Get your first event tracked in under 5 minutes.

Get your first event tracked in under 5 minutes.

Prerequisites

Step 1 — Get your API key

  1. Open your project in the dashboard
  2. Go to Settings
  3. Copy the value of the API key field (prj_ak_...)

Step 2 — Choose your SDK

Pick the package that matches your environment:

EnvironmentPackage
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 SDKREST 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/node

Prefer to let your AI assistant do this? See Install with your AI assistant.

How sessions work

Every SDK follows the same flow:

  1. init_sdk — authenticate with your API key. The server creates a session. Browser SDKs keep the sdk_session cookie and also send the session id in the X-TrichiData-Session header (new in 0.6.0, works with Safari ITP).
  2. identify (optional) — associate userId and/or appVersion with the session. At least one field is required; omitted values default to "anonymous" and "unknown" in events.
  3. Track events — use typed helpers (page, productViewed, …) or trackCustom.

What SDK 0.6.0 adds

  • Anonymous id and sessions — a persistent anonymousId and a clientSessionId (new after 30 minutes of inactivity) are attached to every event. When you call identify, 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. Call await client.flush() to send now.
  • Automatic pageviews (browser and React) — page is tracked on init and on every SPA navigation. If you already call client.page() on each route change, set autoPageviews: false to 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: true sends nothing until client.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

On this page