react-event-tracking 1.0.3 → 1.0.4

package/README.md

@@ -1,3 +1,4 @@
+
 # react-event-tracking [![NPM Version](https://img.shields.io/npm/v/react-event-tracking)](https://www.npmjs.com/package/react-event-tracking)
 A convenient React context for tracking analytics events. 
 
@@ -18,7 +19,7 @@ yarn add react-event-tracking
 
 ## Quickstart
 
-1. Define the root handler (e.g., send to GTM or API)
+1. Define the root handler (e.g., send to GTM, Amplitude or API)
 ```tsx
 import { TrackRoot } from 'react-event-tracking';
 
@@ -56,6 +57,54 @@ const MyButton = () => {
 };
 ```
 
+## Best Practices
+
+A common pattern is to layer data from global to specific. Here is how parameters merge:
+
+```tsx
+// 1. ROOT: Global data (App Version, Environment)
+<TrackRoot onEvent={handleEvent} initialParams={{ appVersion: '1.0.0' }}>
+  
+  {/* 2. PAGE: Screen-level context */}
+  <TrackProvider params={{ page: 'ProductDetails', category: 'Shoes' }}>
+    
+    {/* 3. COMPONENT: Widget-level context */}
+    <TrackProvider params={{ productId: 'sku-999' }}>
+       <AddToCartButton />
+    </TrackProvider>
+
+  </TrackProvider>
+</TrackRoot>
+
+// Inside AddToCartButton:
+const { sendEvent } = useTracker();
+
+// 4. EVENT: Action-specific data
+// When clicked, we only pass what changed right now.
+const handleClick = () => {
+  sendEvent('add_to_cart', { quantity: 1 });
+};
+```
+
+**Resulting Event Payload:**
+The library merges all layers automatically. The handler receives:
+
+
+```js
+{
+  // From Root
+  appVersion: '1.0.0',
+  // From Page Provider
+  page: 'ProductDetails',
+  category: 'Shoes',
+  // From Component Provider
+  productId: 'sku-999',
+  // From Event
+  quantity: 1
+}
+```
+
+
 ## Built-in Hooks   
 
 ### useMountEvent   

package/dist/index.cjs

@@ -16,7 +16,8 @@ const useTracker = () => {
 };
 const TrackRoot = ({
   onEvent,
-  children
+  children,
+  initialParams
 }) => {
   const onEventRef = React.useRef(onEvent);
   onEventRef.current = onEvent;
@@ -24,7 +25,7 @@ const TrackRoot = ({
     onEventRef.current(eventName, params);
   }, []);
   const value = React.useMemo(() => ({ sendEvent }), [sendEvent]);
-  return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
+  return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, /* @__PURE__ */ React__default.createElement(TrackProvider, { params: initialParams || {} }, children));
 };
 const TrackProvider = ({
   params,

package/dist/index.d.cts

@@ -7,8 +7,9 @@ type TrackContextValue = {
 };
 
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+declare const TrackRoot: ({ onEvent, children, initialParams }: PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
+    initialParams?: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;

package/dist/index.d.mts

@@ -7,8 +7,9 @@ type TrackContextValue = {
 };
 
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+declare const TrackRoot: ({ onEvent, children, initialParams }: PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
+    initialParams?: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;

package/dist/index.d.ts

@@ -7,8 +7,9 @@ type TrackContextValue = {
 };
 
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+declare const TrackRoot: ({ onEvent, children, initialParams }: PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
+    initialParams?: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;

package/dist/index.mjs

@@ -10,7 +10,8 @@ const useTracker = () => {
 };
 const TrackRoot = ({
   onEvent,
-  children
+  children,
+  initialParams
 }) => {
   const onEventRef = useRef(onEvent);
   onEventRef.current = onEvent;
@@ -18,7 +19,7 @@ const TrackRoot = ({
     onEventRef.current(eventName, params);
   }, []);
   const value = useMemo(() => ({ sendEvent }), [sendEvent]);
-  return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
+  return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, /* @__PURE__ */ React.createElement(TrackProvider, { params: initialParams || {} }, children));
 };
 const TrackProvider = ({
   params,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-event-tracking",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "files": [
     "dist"
   ],