React

Install EngageTrack in any React application (Vite, CRA, etc.).

React

This guide covers adding EngageTrack to any React application — Vite, Create React App, or any other bundler setup. The SDK is framework-agnostic and works by adding a single script tag.

1. Add the Script to index.html

Open your index.html (in the project root for Vite, or public/index.html for CRA) and add the script inside the <head> tag:

<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>My App</title>
		<script
			defer
			data-site-id="YOUR_SITE_ID"
			src="https://cdn.engagetrack.net/sdk.js"
		></script>
	</head>
	<body>
		<div id="root"></div>
		<script type="module" src="/src/main.tsx"></script>
	</body>
</html>

Replace YOUR_SITE_ID with the Site ID from your EngageTrack dashboard (Site Settings → General).

2. React Router Support

The EngageTrack SDK automatically detects client-side navigations by listening to pushState and replaceState calls on the History API. This means React Router v6+ works out of the box — every route change triggers a pageview.

Hash Routing

If you use HashRouter, add data-hash="true" to the script tag so hash changes are tracked as pageviews:

<script
	defer
	data-site-id="YOUR_SITE_ID"
	data-hash="true"
	src="https://cdn.engagetrack.net/sdk.js"
></script>

3. Track Goals in Components

Call window.engagetrack() from any event handler:

function PricingCard({ plan }: { plan: string }) {
	const handleSelect = () => {
		window.engagetrack("plan-selected", { plan });
	};
 
	return (
		<div className="card">
			<h3>{plan}</h3>
			<button onClick={handleSelect}>Choose {plan}</button>
		</div>
	);
}

Track on Mount

Use useEffect to fire an event when a component mounts (e.g., when a user reaches a specific page):

import { useEffect } from "react";
 
function ThankYouPage() {
	useEffect(() => {
		window.engagetrack("conversion-complete");
	}, []);
 
	return <h1>Thank you for your purchase!</h1>;
}

Always wrap window.engagetrack calls in useEffect or event handlers. Never call it at the top level of a component — it will run during SSR/pre-rendering if you use frameworks like Remix or Next.js.

4. Track Revenue

Use trackPurchase for revenue events:

function CheckoutButton({ amount }: { amount: number }) {
	const handleCheckout = async () => {
		await processPayment();
		window.engagetrack.trackPurchase("order_123", amount, "USD");
	};
 
	return <button onClick={handleCheckout}>Pay ${amount}</button>;
}

5. Environment Variables (Vite)

To avoid hardcoding the Site ID, use Vite environment variables. Create a .env file:

VITE_ENGAGETRACK_SITE_ID=your-site-id-here

Then reference it in index.html using Vite's HTML env replacement:

<script
	defer
	data-site-id="%VITE_ENGAGETRACK_SITE_ID%"
	src="https://cdn.engagetrack.net/sdk.js"
></script>

For Create React App, use REACT_APP_ENGAGETRACK_SITE_ID and %REACT_APP_ENGAGETRACK_SITE_ID% instead.

Verify Installation

Start your dev server (npm run dev or npm start).
Open the app and click through a few pages.
In the EngageTrack dashboard, go to the Realtime tab — your visits should appear within seconds.

If you see your pageviews in Realtime, you're all set. If not, add data-debug="true" to the script tag and check the browser console for diagnostic messages.