@tcgre/clickstream-sdk

A lightweight Web SDK for tracking user behaviour, page views, and custom events.

Installation

npm install @tcgre/clickstream-sdk
# or
yarn add @tcgre/clickstream-sdk

Initialisation

Add this once in your app's entry file (e.g. main.ts or index.ts) and you're good to go.

import { ClickStream } from '@tcgre/clickstream-sdk';

await ClickStream.init({ apiKey: 'your-api-key' });

Options

| Property | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your project API key. | | autoTrackClicks | boolean | false | Automatically capture every DOM click as a click event. | | debug | boolean | false | Enable console logging. Keep this off in production. | | onError | (err: Error) => void | — | Optional callback for handling errors. |

Methods

ClickStream.track(eventName, properties?)

Use this to track anything meaningful in your app — button clicks, form submissions, product views, you name it.

ClickStream.track('property_viewed', {
  property_id: 'prop_987',
  price: 5000000,
});

ClickStream.pageView(properties?)

Call this on every route change to track page views. In a SPA, hook it into your router.

// React Router example
useEffect(() => {
  ClickStream.pageView();
}, [location]);

ClickStream.identify(userId)

Once a user logs in or fills a form, tie their activity to a known ID. If the SDK is already associated with a different user, it will flush queued events for the previous user, end that session, and start a fresh session for the new user before tracking continues. Any events captured while that switch is in progress are buffered and replayed only after the new session is active.

await ClickStream.identify('user_uuid_12345');

ClickStream.setPii(data)

Got a user's phone or email? Pass it here and the SDK will securely attach it to events. Call setPii(null) to clear it on logout.

ClickStream.setPii({
  phone: '+919876543210',
  email: '[email protected]',
  countryCode: '+91',
});

// On logout
ClickStream.setPii(null);

License

MIT