EngageTrack React SDK

A comprehensive React SDK for EngageTrack analytics and user tracking. This package provides the same functionality as the vanilla JavaScript SDK but with React-specific hooks and components for seamless integration.

Features

• 🚀 Easy Integration: Simple React hooks for tracking
• 📊 Real-time Analytics: WebSocket support for live data
• 🔗 Automatic Link Tracking: Captures user interactions automatically
• 📈 Referral Tracking: Built-in referral and UTM parameter tracking
• 🎯 Custom Events: Track any custom event with additional data
• 🔒 Privacy Friendly: Respects user privacy with configurable options
• 💻 TypeScript Support: Full TypeScript definitions included
• 🌐 Universal: Works with SSR/Next.js
• 📱 Mobile Friendly: Optimized for mobile devices

Installation

npm install @asunalabs/tracker-sdk
# or
yarn add @asunalabs/tracker-sdk

Basic Usage

1. Initialize the tracker

import React from "react";
import { useEngageTrack, EngageTrackConfig } from "@asunalabs/tracker-sdk";

const config: EngageTrackConfig = {
	siteId: "your-site-id",
	domain: "your-domain.com",
};

import React from "react";
import { useEngageTrack, EngageTrackConfig } from "@asunalabs/tracker-sdk";

const config: EngageTrackConfig = {
	siteId: "your-site-id",
	domain: "your-domain.com",
};

function App() {
	const { track, sessionData, onlineUsers } = useEngageTrack(config);

	return (
		<div>
			<h1>My App</h1>
			<p>Session ID: {sessionData?.sessionId}</p>
			<p>Online Users: {onlineUsers?.count || 0}</p>
			<button onClick={() => track("custom_event", { action: "button_click" })}>
				Track Custom Event
			</button>
		</div>
	);
}

2. Track custom events

import { useEngageTrack } from "@asunalabs/tracker-sdk";

function MyComponent() {
	const { track } = useEngageTrack(config);

	const handlePurchase = () => {
		track("purchase", {
			amount: 99.99,
			currency: "USD",
			productId: "prod-123",
		});
	};

	return <button onClick={handlePurchase}>Buy Now</button>;
}

3. Track referral conversions

import { useEngageTrack } from "@asunalabs/tracker-sdk";

function SignupForm() {
	const { trackReferralConversion } = useEngageTrack(config);

	const handleSignup = () => {
		// Track that the user signed up (conversion)
		trackReferralConversion({
			conversionType: "signup",
			value: "free_trial",
		});
	};

	return <button onClick={handleSignup}>Sign Up</button>;
}

Configuration Options

interface EngageTrackConfig {
	siteId: string; // Required: Your site ID
	domain: string; // Required: Your domain
}

Event Hooks

You can listen to various events using the hooks parameter:

const { track } = useEngageTrack(config, {
	onTrackingEvent: (eventType, data) => {
		console.log("Event tracked:", eventType, data);
	},
	onSessionStart: (sessionData) => {
		console.log("Session started:", sessionData);
	},
	onSessionEnd: (sessionData) => {
		console.log("Session ended:", sessionData);
	},
	onWebSocketConnect: () => {
		console.log("WebSocket connected");
	},
	onWebSocketDisconnect: () => {
		console.log("WebSocket disconnected");
	},
	onOnlineUsersUpdate: (users) => {
		console.log("Online users updated:", users);
	},
	onReferralConversion: (referralData) => {
		console.log("Referral conversion:", referralData);
	},
	onError: (error) => {
		console.error("EngageTrack error:", error);
	},
});

Available Event Types

• page_view - Page view tracking
• page_load - Page load event
• page_unload - Page unload event
• page_hidden - Page hidden (tab switch)
• user_click - User click event
• idle_timeout - User idle timeout
• session_start - Session start
• session_end - Session end
• referral_conversion - Referral conversion
• custom_event - Custom event

Advanced Usage

Manual Tracking Only

const config: EngageTrackConfig = {
	siteId: "your-site-id",
	domain: "your-domain.com",
};

const { track } = useEngageTrack(config);

// Manually track what you need
track("page_view", { customData: "value" });

Next.js Integration

// pages/_app.tsx
import { useEngageTrack } from "@asunalabs/tracker-sdk";
import { useRouter } from "next/router";
import { useEffect } from "react";

function MyApp({ Component, pageProps }) {
	const router = useRouter();
	const { track } = useEngageTrack({
		siteId: process.env.NEXT_PUBLIC_SITE_ID,
		domain: process.env.NEXT_PUBLIC_DOMAIN,
	});

	useEffect(() => {
		const handleRouteChange = (url) => {
			track("page_view", { url });
		};

		router.events.on("routeChangeComplete", handleRouteChange);
		return () => {
			router.events.off("routeChangeComplete", handleRouteChange);
		};
	}, [router.events, track]);

	return <Component {...pageProps} />;
}

Custom Event Tracking

// Track e-commerce events
const trackPurchase = (orderData) => {
	track("purchase", {
		orderId: orderData.id,
		amount: orderData.total,
		currency: orderData.currency,
		items: orderData.items.map((item) => ({
			id: item.id,
			name: item.name,
			price: item.price,
			quantity: item.quantity,
		})),
	});
};

// Track user engagement
const trackVideoWatch = (videoId, duration) => {
	track("video_watch", {
		videoId,
		duration,
		timestamp: Date.now(),
	});
};

// Track form submissions
const trackFormSubmission = (formName, fields) => {
	track("form_submit", {
		formName,
		fields: Object.keys(fields),
		timestamp: Date.now(),
	});
};

Utility Functions

The SDK exports several utility functions:

import {
	generateId,
	setCookie,
	getCookie,
	getReferralData,
	parseReferralParams,
	detectReferralSource,
} from "@engagetrack/react";

// Generate a unique ID
const uniqueId = generateId();

// Work with cookies
setCookie("custom_cookie", "value", 30); // 30 days
const value = getCookie("custom_cookie");

// Get referral information
const referralData = getReferralData();
const urlParams = parseReferralParams();
const referralSource = detectReferralSource();

TypeScript Support

Full TypeScript support is included with comprehensive type definitions:

import {
	EngageTrackConfig,
	EventType,
	TrackingData,
	SessionData,
	OnlineUsersData,
	ReferralData,
} from "@engagetrack/react";

// Type-safe configuration
const config: EngageTrackConfig = {
	siteId: "site-123",
	domain: "example.com",
};

// Type-safe event tracking
const trackEvent = (eventType: EventType, data: TrackingData) => {
	track(eventType, data);
};

Privacy and GDPR Compliance

The SDK is designed with privacy in mind:

• Only collects necessary analytics data
• Respects user privacy settings
• Supports opt-out mechanisms
• Uses secure, same-site cookies
• No third-party tracking

To disable tracking:

// Set this in localStorage to disable tracking
localStorage.setItem("engageTrackDisabled", "true");

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Start development mode
npm run dev

# Run example
npm run example

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• GitHub Issues: github.com/asunalabs/tracker-sdk/issues
• Documentation: docs.asunalabs.com
• Email: [email protected]