React SDK

Use this guide when your app is built with React 18+.

For session flow and event schemas, see the REST API. For a guided first integration, see Quickstart.

Installation

npm install @trichidata/react

Requires react >= 18 as a peer dependency.

Setup

Provider

Wrap your application tree with TrichiDataProvider:

import { TrichiDataProvider } from '@trichidata/react';

function App() {
  return (
    <TrichiDataProvider apiKey="prj_ak_xxxxxxxxxxxx">
      <Routes />
    </TrichiDataProvider>
  );
}

Props

Prop	Type	Default	Description
`apiKey`	`string`	required	Project write key
`autoInit`	`boolean`	`true`	Call `init()` on mount
`device`	`Partial<DeviceInfo>`	—	Override auto-detected device fields
`tracking`	`TrackingContext`	—	Override auto-parsed GA/Meta cookies

When autoInit is true, the provider calls init_sdk with browser device info and tracking (cookies when available, otherwise a generated GA-like clientId) on mount. Session cookies are handled automatically in the browser.

Hook

Use useTrichiData() to access the client anywhere inside the provider:

import { useTrichiData } from '@trichidata/react';

function CheckoutButton() {
  const client = useTrichiData();

  const handleClick = async () => {
    await client.checkoutStarted({
      total: 99.9,
      currency: 'USD',
      items: [{ productId: 'p1', name: 'Widget', price: 99.9, quantity: 1 }],
    });
  };

  return <button onClick={handleClick}>Checkout</button>;
}

useTrichiData() returns a TrichiDataClient instance. It throws if used outside TrichiDataProvider.

Manual initialization

Set autoInit={false} when you need to control when init() runs:

<TrichiDataProvider apiKey="prj_ak_xxx" autoInit={false}>
  <App />
</TrichiDataProvider>

import { useTrichiData } from '@trichidata/react';

function App() {
  const client = useTrichiData();

  useEffect(() => {
    void client.init();
  }, [client]);

  return <Routes />;
}

React-specific exports

Export	Purpose
`TrichiDataProvider`	Context provider with optional auto-init
`useTrichiData`	Hook to access `TrichiDataClient`
`getPageContext()`	Current page `title`, `url`, `referrer`

Client methods

Method	Description
`init(params?)`	Start a session (`init_sdk`)
`identify({ userId?, appVersion? })`	Associate session context — at least one field required
`page` / `productViewed` / …	Typed helpers for reserved event names
`trackCustom(name, properties?)`	Custom (non-reserved) event

See REST API for reserved eventName values and properties schemas.