@journium/react 1.0.0 → 1.0.2

package/readme.md

@@ -8,17 +8,40 @@
 
 The official React SDK for Journium providing hooks, providers, and components for seamless analytics integration in React applications.
 
-## 🚀 Quick Start
-
-### Installation
+## Installation
 
+### npm
 ```bash
 npm install @journium/react
 ```
 
-### Basic Setup
+### pnpm
+```bash
+pnpm add @journium/react
+```
+
+### yarn
+```bash
+yarn add @journium/react
+```
 
-Wrap your app with the `JourniumProvider`:
+## Basic Setup
+
+### Environment Variables
+First, create a `.env.local` file in your project root:
+
+**Note:** For CRA projects, use `REACT_APP_` prefix:
+```env
+REACT_APP_JOURNIUM_PUBLISHABLE_KEY=your-actual-publishable-key-here
+```
+
+**Note:** For Vite projects, use `VITE_` prefix:
+```env
+VITE_JOURNIUM_PUBLISHABLE_KEY=your-actual-publishable-key-here
+```
+
+### Initialize Journium
+Wrap your app with the `JourniumProvider` to enable analytics throughout your React application.
 
 ```jsx
 import React from 'react';
@@ -29,13 +52,8 @@ function Root() {
   return (
     <JourniumProvider
       config={{
-        token: "your-journium-token",
-        apiHost: "https://your-journium-instance.com",
-        debug: true, // Optional: Enable debug logging
-        flushAt: 5,  // Optional: Send events after 5 events
-        flushInterval: 10000 // Optional: Send events every 10 seconds
+        publishableKey: process.env.REACT_APP_JOURNIUM_PUBLISHABLE_KEY!
       }}
-      autoCapture={true} // Enables auto-pageview and click tracking
     >
       <App />
     </JourniumProvider>
@@ -45,9 +63,40 @@ function Root() {
 export default Root;
 ```
 
-### Track Custom Events
+**Vite Example:**
+```jsx
+// main.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { JourniumProvider } from '@journium/react';
+import App from './App';
 
-Use the `useTrackEvent` hook to track custom events:
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <JourniumProvider
+      config={{
+        publishableKey: import.meta.env.VITE_JOURNIUM_PUBLISHABLE_KEY!
+      }}
+    >
+      <App />
+    </JourniumProvider>
+  </React.StrictMode>
+);
+```
+
+**Vite .env file:**
+```env
+VITE_JOURNIUM_PUBLISHABLE_KEY=your-actual-publishable-key-here
+```
+
+**For Next.js applications, use the dedicated [`@journium/nextjs`](../journium-nextjs) package instead.**
+
+### API Classes and Types
+
+The main analytics class is `JourniumAnalytics`, available through the React hooks and context.
+
+### Track a Custom Event
+Use the `useTrackEvent` hook to track custom events from any component.
 
 ```jsx
 import React from 'react';
@@ -62,75 +111,29 @@ function SignupButton() {
       source: 'landing_page',
       plan: 'free'
     });
-    // Your signup logic
   };
 
   return <button onClick={handleSignup}>Sign Up</button>;
 }
 ```
 
-## 📖 Tracking Hooks
-
-### useTrackEvent - Track Custom Events
-
-The primary hook for tracking custom business events:
-
-```jsx
-import { useTrackEvent } from '@journium/react';
-
-function EcommerceComponent() {
-  const trackEvent = useTrackEvent();
-
-  const handlePurchase = () => {
-    trackEvent('purchase_completed', {
-      product_id: 'prod_123',
-      price: 29.99,
-      currency: 'USD',
-      category: 'electronics'
-    });
-  };
-
-  const handleAddToCart = () => {
-    trackEvent('product_added_to_cart', {
-      product_id: 'prod_123',
-      quantity: 1,
-      source: 'product_page'
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={handleAddToCart}>Add to Cart</button>
-      <button onClick={handlePurchase}>Buy Now</button>
-    </div>
-  );
-}
-```
-
-### useIdentify - User Identification
-
-Use this hook to identify users when they log in or sign up. This should be used instead of tracking user login as a custom event.
+### Identify a User
+Use the `useIdentify` hook to identify users when they log in or sign up.
 
 ```jsx
+import React from 'react';
 import { useIdentify } from '@journium/react';
 
 function LoginForm() {
   const identify = useIdentify();
 
   const handleLogin = async (email, password) => {
-    try {
-      const user = await loginUser(email, password);
-      
-      // Identify the user after successful login
-      identify(user.id, {
-        name: user.name,
-        email: user.email,
-      });
-      
-      // Redirect to dashboard or show success
-    } catch (error) {
-      // Handle login error
-    }
+    const user = await loginUser(email, password);
+    
+    identify(user.id, {
+      name: user.name,
+      email: user.email
+    });
   };
 
   return (
@@ -141,370 +144,225 @@ function LoginForm() {
 }
 ```
 
-### useReset - User Logout
-
-Use this hook to reset user identity when they log out:
+### Reset User Identity
+Use the `useReset` hook to reset user identity when they log out.
 
 ```jsx
+import React from 'react';
 import { useReset } from '@journium/react';
 
 function LogoutButton() {
   const reset = useReset();
 
   const handleLogout = async () => {
-    try {
-      await logoutUser();
-      
-      // Reset user identity after successful logout
-      reset();
-      
-      // Redirect to home or login page
-    } catch (error) {
-      // Handle logout error
-    }
+    await logoutUser();
+    reset();
   };
 
   return <button onClick={handleLogout}>Log Out</button>;
 }
 ```
 
-### useTrackPageview - Manual Pageview Tracking
-
-For tracking custom pageviews beyond automatic route tracking:
+## Advanced Setup
+You can override default configurations and control autocapture:
 
+**React/CRA Example:**
 ```jsx
-import { useTrackPageview } from '@journium/react';
-
-function CustomPageTracker() {
-  const trackPageview = useTrackPageview();
-
-  const handleSpecialPageview = () => {
-    trackPageview({
-      page_type: 'modal',
-      content_type: 'pricing_calculator',
-      user_segment: 'premium'
-    });
-  };
+import React from 'react';
+import { JourniumProvider } from '@journium/react';
+import App from './App';
 
+function Root() {
   return (
-    <button onClick={handleSpecialPageview}>
-      Track Modal View
-    </button>
+    <JourniumProvider
+      config={{
+        publishableKey: process.env.REACT_APP_JOURNIUM_PUBLISHABLE_KEY!,
+        apiHost: 'https://events.journium.app',
+        options: {
+          debug: process.env.REACT_APP_JOURNIUM_DEBUG === 'true',
+          flushAt: 5,                    // Send events after N events
+          flushInterval: 10000,          // Send events every N milliseconds
+          sessionTimeout: 1800000,       // Session timeout (30 minutes)
+          autoTrackPageviews: true,      // Automatically track pageview events (default: true)
+          autocapture: {                 // Configure automatic event capture
+            captureClicks: true,         // Track click events
+            captureFormSubmits: true,    // Track form submissions
+            captureFormChanges: false,   // Track form field changes
+            ignoreClasses: ['no-track', 'sensitive'], // CSS classes to ignore
+            ignoreElements: ['input[type="password"]'] // Elements to ignore
+          }
+        }
+      }}
+    >
+      <App />
+    </JourniumProvider>
   );
 }
-```
 
-### useAutoTrackPageview - Automatic Pageview on Mount
-
-Automatically track pageviews when components mount or dependencies change:
+export default Root;
+```
 
+**Vite Example:**
 ```jsx
-import { useAutoTrackPageview } from '@journium/react';
-
-function ProductPage({ productId, category }) {
-  // Tracks pageview when component mounts or productId changes
-  useAutoTrackPageview([productId], {
-    page_type: 'product_detail',
-    product_id: productId,
-    category: category
-  });
+import React from 'react';
+import { JourniumProvider } from '@journium/react';
+import App from './App';
 
-  return <div>Product {productId}</div>;
+function Root() {
+  return (
+    <JourniumProvider
+      config={{
+        publishableKey: import.meta.env.VITE_JOURNIUM_PUBLISHABLE_KEY!,
+        apiHost: 'https://events.journium.app',
+        options: {
+          debug: import.meta.env.VITE_JOURNIUM_DEBUG === 'true',
+          flushAt: 5,
+          flushInterval: 10000,
+          sessionTimeout: 1800000,
+          autoTrackPageviews: true,
+          autocapture: {
+            captureClicks: true,
+            captureFormSubmits: true,
+            captureFormChanges: false,
+            ignoreClasses: ['no-track', 'sensitive'],
+            ignoreElements: ['input[type="password"]']
+          }
+        }
+      }}
+    >
+      <App />
+    </JourniumProvider>
+  );
 }
 
-function BlogPost({ postId }) {
-  // Track pageview for blog posts
-  useAutoTrackPageview([postId], {
-    page_type: 'blog_post',
-    post_id: postId,
-    content_type: 'article'
-  });
-
-  return <article>Blog post content</article>;
-}
+export default Root;
 ```
 
-## 🔧 Advanced Usage
+## API Reference
 
-### Form Tracking
+### Components
 
-Track form interactions and submissions:
+#### `<JourniumProvider>`
+Provider component that initializes Journium analytics throughout your React application.
 
-```jsx
-import { useTrackEvent } from '@journium/react';
+**Props:**
+- `config: JourniumConfig` - Configuration object for Journium
+  - `publishableKey: string` - Your Journium publishable key (required)
+  - `apiHost?: string` - Custom API endpoint (optional, defaults to 'https://events.journium.app')
+  - `options?: JourniumLocalOptions` - Local configuration options (optional)
+- `children: ReactNode` - React children to wrap
 
-function ContactForm() {
-  const trackEvent = useTrackEvent();
+### Hooks
 
-  const handleSubmit = (e) => {
-    e.preventDefault();
-    
-    trackEvent('form_submitted', {
-      form_name: 'contact',
-      form_type: 'lead_generation',
-      fields_completed: ['name', 'email', 'company']
-    });
-    
-    // Submit form logic
-  };
+#### `useTrackEvent()`
+Returns a function to track custom events.
 
-  const handleFieldChange = (fieldName) => {
-    trackEvent('form_field_completed', {
-      form_name: 'contact',
-      field_name: fieldName
-    });
-  };
+**Returns:** `(event: string, properties?: Record<string, unknown>) => void`
+- `event: string` - Event name to track
+- `properties?: Record<string, unknown>` - Optional event properties
 
-  return (
-    <form onSubmit={handleSubmit}>
-      <input 
-        name="email" 
-        onChange={() => handleFieldChange('email')}
-        placeholder="Email"
-      />
-      <input 
-        name="company" 
-        onChange={() => handleFieldChange('company')}
-        placeholder="Company"
-      />
-      <button type="submit">Send Message</button>
-    </form>
-  );
-}
-```
+#### `useIdentify()`
+Returns a function to identify users.
 
-### User Journey Tracking
+**Returns:** `(distinctId: string, attributes?: Record<string, unknown>) => void`
+- `distinctId: string` - Unique user identifier
+- `attributes?: Record<string, unknown>` - Optional user attributes
 
-Track multi-step user flows:
+#### `useReset()`
+Returns a function to reset user identity (typically on logout).
 
-```jsx
-import { useTrackEvent, useTrackPageview } from '@journium/react';
-
-function OnboardingFlow({ step }) {
-  const trackEvent = useTrackEvent();
-  const trackPageview = useTrackPageview();
-
-  useEffect(() => {
-    // Track onboarding step pageview
-    trackPageview({
-      page_type: 'onboarding',
-      step: step,
-      flow: 'user_setup'
-    });
-  }, [step, trackPageview]);
-
-  const handleStepComplete = () => {
-    trackEvent('onboarding_step_completed', {
-      step: step,
-      time_spent: Date.now() - stepStartTime,
-      completed_successfully: true
-    });
-  };
+**Returns:** `() => void`
 
-  const handleSkipStep = () => {
-    trackEvent('onboarding_step_skipped', {
-      step: step,
-      reason: 'user_choice'
-    });
-  };
+#### `useTrackPageview()`
+Returns a function to manually track pageview events.
 
-  return (
-    <div>
-      <h2>Step {step}</h2>
-      <button onClick={handleStepComplete}>Complete Step</button>
-      <button onClick={handleSkipStep}>Skip</button>
-    </div>
-  );
-}
-```
+**Returns:** `(properties?: Record<string, unknown>) => void`
+- `properties?: Record<string, unknown>` - Optional pageview properties
 
-### Feature Usage Tracking
+#### `useAutoTrackPageview()`
+Automatically tracks pageview when component mounts or dependencies change.
 
-Create reusable tracking patterns:
+**Parameters:**
+- `dependencies?: React.DependencyList` - Dependencies to watch for changes (defaults to empty array)
+- `properties?: Record<string, unknown>` - Optional pageview properties
 
-```jsx
-import { useTrackEvent } from '@journium/react';
+**Returns:** `void`
 
-// Custom hook for feature tracking
-function useFeatureTracking() {
-  const trackEvent = useTrackEvent();
+#### `useAutocapture()`
+Returns functions to control automatic event capture.
 
-  const trackFeatureUsed = (featureName, context = {}) => {
-    trackEvent('feature_used', {
-      feature_name: featureName,
-      timestamp: new Date().toISOString(),
-      ...context
-    });
-  };
+**Returns:** `{ startAutocapture: () => void, stopAutocapture: () => void }`
+- `startAutocapture()` - Enable automatic event capture
+- `stopAutocapture()` - Disable automatic event capture
 
-  const trackFeatureDiscovered = (featureName, discoveryMethod) => {
-    trackEvent('feature_discovered', {
-      feature_name: featureName,
-      discovery_method: discoveryMethod
-    });
-  };
+#### `useJournium()`
+Returns the Journium context for advanced use cases.
 
-  return { trackFeatureUsed, trackFeatureDiscovered };
-}
+**Returns:** `JourniumContextValue`
+- `analytics: JourniumAnalytics | null` - The analytics instance
+- `config: JourniumConfig | null` - The configuration object
+- `effectiveOptions: JourniumLocalOptions | null` - The effective options (merged local and remote)
 
-// Usage in components
-function AdvancedFeature() {
-  const { trackFeatureUsed, trackFeatureDiscovered } = useFeatureTracking();
+### Types
 
-  const handleFeatureClick = () => {
-    trackFeatureUsed('advanced_search', {
-      search_type: 'filters',
-      filter_count: 3
-    });
-  };
+#### `JourniumConfig`
+Configuration object for initializing Journium.
 
-  return (
-    <div>
-      <button onClick={handleFeatureClick}>
-        Use Advanced Search
-      </button>
-    </div>
-  );
+```typescript
+interface JourniumConfig {
+  publishableKey: string;
+  apiHost?: string;
+  options?: JourniumLocalOptions;
 }
 ```
 
-## 🔒 Privacy & GDPR Compliance
+#### `JourniumLocalOptions`
+Local configuration options that can be set on the client.
 
-### User Consent Management
-
-Control tracking based on user consent:
-
-```jsx
-import { useState, useEffect } from 'react';
-import { useAutocapture } from '@journium/react';
-
-function ConsentBanner() {
-  const { startAutocapture, stopAutocapture } = useAutocapture();
-  const [hasConsent, setHasConsent] = useState(null);
-
-  useEffect(() => {
-    const savedConsent = localStorage.getItem('tracking_consent');
-    if (savedConsent === 'true') {
-      setHasConsent(true);
-      startAutocapture();
-    } else if (savedConsent === 'false') {
-      setHasConsent(false);
-      stopAutocapture();
-    }
-  }, [startAutocapture, stopAutocapture]);
-
-  const handleAccept = () => {
-    setHasConsent(true);
-    localStorage.setItem('tracking_consent', 'true');
-    startAutocapture();
+```typescript
+interface JourniumLocalOptions {
+  debug?: boolean;                    // Enable debug logging
+  flushAt?: number;                   // Number of events before auto-flush
+  flushInterval?: number;             // Flush interval in milliseconds
+  autocapture?: boolean | AutocaptureOptions; // Auto-capture configuration
+  autoTrackPageviews?: boolean;       // Automatic pageview tracking
+  sessionTimeout?: number;            // Session timeout in milliseconds
+  sampling?: {
+    enabled?: boolean;
+    rate?: number;
   };
-
-  const handleDecline = () => {
-    setHasConsent(false);
-    localStorage.setItem('tracking_consent', 'false');
-    stopAutocapture();
+  features?: {
+    enableGeolocation?: boolean;
+    enableSessionRecording?: boolean;
+    enablePerformanceTracking?: boolean;
   };
-
-  if (hasConsent !== null) return null;
-
-  return (
-    <div className="consent-banner">
-      <p>We use analytics to improve your experience.</p>
-      <button onClick={handleAccept}>Accept</button>
-      <button onClick={handleDecline}>Decline</button>
-    </div>
-  );
 }
 ```
 
-### Excluding Sensitive Data
-
-Configure autocapture to ignore sensitive elements:
-
-```jsx
-<JourniumProvider
-  config={{
-    token: "your-token",
-    apiHost: "https://api.journium.com",
-    autocapture: {
-      captureClicks: true,
-      captureFormSubmits: true,
-      captureFormChanges: false,
-      ignoreClasses: ['no-track', 'sensitive', 'pii'],
-      ignoreElements: ['input[type="password"]', '.credit-card']
-    }
-  }}
->
-  <App />
-</JourniumProvider>
-```
-
-## 📱 TypeScript Support
-
-Full TypeScript support with complete type definitions:
+#### `AutocaptureOptions`
+Configuration for automatic event capture.
 
 ```typescript
-import { useTrackEvent, JourniumConfig } from '@journium/react';
-
-interface PurchaseEventProperties {
-  product_id: string;
-  category: string;
-  price: number;
-  currency: string;
-}
-
-function TypedComponent() {
-  const trackEvent = useTrackEvent();
-
-  const handlePurchase = (productData: PurchaseEventProperties) => {
-    // Fully typed event tracking
-    trackEvent('product_purchased', productData);
-  };
-
-  return <button onClick={handlePurchase}>Purchase</button>;
+interface AutocaptureOptions {
+  captureClicks?: boolean;            // Capture click events
+  captureFormSubmits?: boolean;       // Capture form submissions
+  captureFormChanges?: boolean;       // Capture form field changes
+  captureTextSelection?: boolean;     // Capture text selection events
+  ignoreClasses?: string[];           // CSS classes to ignore
+  ignoreElements?: string[];          // HTML elements to ignore
+  captureContentText?: boolean;       // Capture element text content
 }
 ```
 
-## 🔗 Available Hooks
-
-| Hook | Purpose | Usage |
-|------|---------|-------|
-| `useTrackEvent()` | Track custom events | `trackEvent('event_name', properties)` |
-| `useIdentify()` | Identify users on login/signup | `identify(distinctId, attributes)` |
-| `useReset()` | Reset user identity on logout | `reset()` |
-| `useTrackPageview()` | Manual pageview tracking | `trackPageview(properties)` |
-| `useAutoTrackPageview(deps, props)` | Automatic pageview on mount | Auto-tracks when deps change |
-| `useAutocapture()` | Control autocapture | `{ startAutocapture, stopAutocapture }` |
-| `useJournium()` | Direct Journium instance access | Advanced use cases only |
-
-## 🔗 Related Packages
-
-Part of the Journium JavaScript SDK ecosystem:
-
-- **[journium-js](https://npmjs.com/package/journium-js)** - Core JavaScript SDK for web browsers
-- **[@journium/nextjs](https://npmjs.com/package/@journium/nextjs)** - Next.js integration with SSR support
-- **[@journium/node](https://npmjs.com/package/@journium/node)** - Node.js server-side tracking
-- **[@journium/core](https://npmjs.com/package/@journium/core)** - Core utilities and types
-
-## 📖 Documentation
-
-For complete documentation, guides, and examples:
-
-- **[Documentation](https://docs.journium.app)** - Complete guides and API reference
-- **[React Guide](https://docs.journium.app/react)** - React-specific documentation
-- **[Examples](https://docs.journium.app/examples/react)** - React code examples and patterns
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](https://github.com/journium/journium-js/blob/main/CONTRIBUTING.md).
-
-## 📄 License
-
-MIT License - see [LICENSE](https://github.com/journium/journium-js/blob/main/LICENSE) file for details.
-
-## 🆘 Support
-
-- **📚 Docs**: [docs.journium.app](https://docs.journium.app)
-- **🐛 Issues**: [GitHub Issues](https://github.com/journium/journium-js/issues)
-- **💬 Discussions**: [GitHub Discussions](https://github.com/journium/journium-js/discussions)
-- **📧 Email**: support@journium.com
+#### `JourniumAnalytics`
+The main analytics class instance available through hooks.
+
+**Methods:**
+- `track(event: string, properties?: Record<string, unknown>): void` - Track custom event
+- `identify(distinctId: string, attributes?: Record<string, unknown>): void` - Identify user
+- `reset(): void` - Reset user identity
+- `capturePageview(properties?: Record<string, unknown>): void` - Track pageview
+- `startAutocapture(): void` - Start automatic event capture
+- `stopAutocapture(): void` - Stop automatic event capture
+- `flush(): void` - Flush pending events immediately
+- `getEffectiveOptions(): JourniumLocalOptions` - Get effective configuration