React SDK for EngageTrack analytics and user tracking
npm install @asunalabs/tracker-sdkbash
npm install @asunalabs/tracker-sdk
or
yarn add @asunalabs/tracker-sdk
`
Basic Usage
$3
`tsx
import React from "react";
import { useEngageTrack, EngageTrackConfig } from "@asunalabs/tracker-sdk";
const config: EngageTrackConfig = {
siteId: "your-site-id",
domain: "your-domain.com",
};
`
`tsx
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 (
My App
Session ID: {sessionData?.sessionId}
Online Users: {onlineUsers?.count || 0}
);
}
`
$3
`tsx
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 ;
}
`
$3
`tsx
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 ;
}
`
Configuration Options
`typescript
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:
`tsx
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
$3
`tsx
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" });
`
$3
`tsx
// 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
}
`
$3
`tsx
// 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:
`tsx
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:
`typescript
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:
`javascript
// Set this in localStorage to disable tracking
localStorage.setItem("engageTrackDisabled", "true");
`
Development
`bash
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
``