react-contextual-analytics


A React framework for collecting and emitting analytics events with minimal boilerplate. Automatically collects context through component boundaries, making analytics implementation simpler and more maintainable.

Quick Start

``bash


Install

npm install react-contextual-analytics

or

yarn add react-contextual-analytics

or

pnpm add react-contextual-analytics
`

`jsx
// 1. Create your analytics client
import {
createAnalyticsClient,
AnalyticsProvider,
AnalyticsBoundary
} from 'react-contextual-analytics';
import { console, google } from 'react-contextual-analytics/providers';

const analyticsClient = createAnalyticsClient([
console, // For development logging
google, // For Google Analytics
]);

// 2. Wrap your app
function App() {
return (



);
}

// 3. Start collecting analytics
function ProductPage({ product }) {
return (
name="product-page"
attributes={{ productId: product.id }}
sendViewedEvent={true}
>
{({ emit }) => (
emit('clicked', 'add-to-cart')}>
Add to Cart

)}

);
}
`

Key Concepts

$3


- Wrap components with AnalyticsBoundary to define context
- Context is automatically inherited from parent boundaries
- Events include all relevant context from their location in the tree

`jsx
import { AnalyticsBoundary } from 'react-contextual-analytics';

function StorePage() {
return (


{({ emit }) => (
emit('clicked', 'view-details')}>
View Product

)}


);
}
// Event includes: {
// boundary: "store.product",
// context: { storeId: "123", productId: "456" }
// }
`

$3

Two ways to emit events:

1. Using Boundary Callback (recommended for multiple events):
`jsx
import { AnalyticsBoundary } from 'react-contextual-analytics';

function CheckoutForm() {
return (

{({ emit }) => (



)}

);
}
`

2. Using Hook (for single events):
`jsx
import { useAnalytics } from 'react-contextual-analytics';

function AddToCartButton({ productId }) {
const { emit } = useAnalytics();

return (
onClick={() => emit('clicked', 'add-to-cart', { productId })}
>
Add to Cart

);
}
`

$3


`typescript
interface Event {
action: string; // e.g., 'clicked', 'viewed'
name?: string; // e.g., 'add-to-cart', 'purchase'
boundary?: string; // e.g., 'store.product'
attributes?: object; // Event-specific data
context?: { // Automatically collected
href: string;
windowWidth: number;
// ... other global context
};
}
`

Best Practices

1. Boundary Organization
- Place boundaries around logical sections (pages, features, forms)
- Keep hierarchy shallow (2-3 levels)
- Use meaningful names

2. Context Management
- Define context at highest relevant level
- Use consistent attribute names
- Avoid context duplication

3. Event Naming
- Use consistent actions: 'clicked', 'viewed', 'submitted'
- Make names descriptive but concise
- Follow consistent patterns

Custom Providers

Create custom providers by implementing the Provider interface:

`typescript
interface Provider {
id: string;
send: (event: Event) => Promise;
setup?: () => void;
}

// Example: Sentry Provider
const sentryProvider = {
id: 'sentry',
send: (event) => {
captureBreadcrumb({
message: [event.boundary, event.name, event.action].filter(Boolean).join(' '),
level: 'info',
});
}
};
`

API Reference

- AnalyticsProvider: Root provider component
- AnalyticsBoundary: Context boundary component
- useAnalytics: Hook for emitting events
- createAnalyticsClient`: Create analytics client with providers