hook

A custom React hook returned as the second array item from createTracker.
It provides access to tracking functionality and context management within your components.


import { createTracker } from "@offlegacy/event-tracker";
 
const [Track, useTracker] = createTracker({...})
 
function MyComponent() {
  const { setContext, getContext, events, send } = useTracker();
 
  return (
    // Your component content
  );
}

Return Value

The hook returns an object with the following properties:

setContext

Type: (params: unknown) => void
Sets or updates the current tracking context
Can be used to update user information, session data, etc.


const { setContext } = useTracker();
 
// Set new context
setContext({ userId: "user-123" });
 
// Update context based on previous value
setContext((prev) => ({
  ...prev,
  lastActive: new Date(),
}));

getContext

Type: () => unknown
Returns the current tracking context
Useful for accessing current tracking state


const { getContext } = useTracker();
 
const currentContext = getContext();
console.log("Current user:", currentContext.userId);

events

Type: Record<keyof EventNames, (params: unknown) => void>
Object containing all configured event tracking functions
Keys match the event names defined in your tracker configuration


const { events } = useTracker();
 
// Track a click event
events.onClick({ buttonId: "submit" });
 
// Track an impression
events.onImpression({ elementId: "hero" });

send

Type: (params: unknown) => void
Generic event sending function
Uses the send function configured in createTracker


const { send } = useTracker();
 
// Send a custom event
send({
  eventType: "custom_action",
  data: {
    /* ... */
  },
});

Example Usage

Here’s a complete example showing how to use the custom hook:


import { createTracker } from "@offlegacy/event-tracker";
 
const [Track, useTracker] = createTracker({
  send: (params) => {
    // Send event to analytics service
    analytics.track(params);
  },
});
 
function UserProfile({ userId }) {
  const { setContext, events, send } = useTracker();
 
  useEffect(() => {
    // Update context when user ID changes
    setContext({ userId });
 
    // Track page view
    events.onPageView({ page: "profile" });
  }, [userId]);
 
  const handleSettingsClick = () => {
    // Track custom event
    send({
      eventType: "open_settings",
      userId,
    });
  };
 
  return (
    <div>
      <h1>User Profile</h1>
      <button onClick={handleSettingsClick}>Settings</button>
    </div>
  );
}

Best Practices

Context Updates
- Use setContext for global state that affects multiple events
- Consider using the function form of setContext for updates based on previous state
Event Tracking
- Use the specific event functions from events when possible
- Fall back to send for custom or one-off events
Performance
- Avoid calling tracking functions in render
- Use callbacks or effects for tracking
- Consider using batching for better performance