react-native-event-logger/README.md

A React Native event tracking library with debug capabilities

# React Native Event Logger

A lightweight React Native library for event tracking and debugging with a beautiful UI. Perfect for development debugging, QA testing, and production monitoring of analytics events.

## 🚀 Features

- **Simple API**: Easy-to-use event logging with just one function
- **Beautiful UI**: Built-in debug screen with expandable event details
- **Real-time Updates**: Events appear instantly in the debug screen
- **TypeScript Support**: Full TypeScript support with type safety
- **Validation Support**: Built-in Firebase-compatible event validation
- **Error Display**: Visual validation error indicators with red headers
- **Search**: Find events quickly with real-time search
- **Event Types**: Categorize events by type for better organization

## 📦 Installation

```bash
npm install react-native-event-logger
```

## 🎯 Quick Start

### 1. Wrap Your App

```tsx
import { EventTrackerProvider } from 'react-native-event-logger';

function App() {
  return (
    <EventTrackerProvider>
      <YourApp />
    </EventTrackerProvider>
  );
}
```

### 2. Basic Event Logging

```tsx
import { logEvent } from 'react-native-event-logger';

if (!isProd) {
    logEvent(eventName,{...params},eventType);

    try {
        FirebaseAnalytics()
            .logEvent(name, { ...commonUserInfo, ...params })
            .catch(error => {
                logger.log('Error while logging GA Events', error);
            });
    } catch (error: any) {
        logSentryException(error, 'Error while tracking GA event');
    }
```

### 3. Display Events (Debug Screen)

```tsx
import { EventDebugScreen } from 'react-native-event-logger';

function DebugScreen() {
  return <EventDebugScreen />;
}
```

## 📚 API Reference

### Components

#### `EventTrackerProvider`
Wraps your app and provides event tracking context.

```tsx
<EventTrackerProvider>
  <YourApp />
</EventTrackerProvider>
```

#### `EventDebugScreen`
Displays all logged events with expandable details.

```tsx
<EventDebugScreen />
```

### Functions

#### `logEvent(eventName, params, eventType?)`
Logs an event with the given name and parameters.

```tsx
logEvent('button_press', {
  button_name: 'checkout',
  user_id: '123'
}, 'firebase_event');
```

**Parameters:**
- `eventName` (string): Name of the event
- `params` (object): Event parameters
- `eventType` (string, optional): Type of event (e.g., 'firebase_event', 'adjust_event', 'facebook_event')

#### `validateFirebaseEvent(eventName, params)`
Validates events against Firebase rules.

```tsx
import { validateFirebaseEvent } from 'react-native-event-logger';

const validation = validateFirebaseEvent('user_login', { method: 'email' });
if (validation.errorMsg) {
  console.warn('Validation failed:', validation.errorMsg);
}
```

## 📊 Event Data Structure

Events are stored with the following structure:

```tsx
interface EventData {
  id: string;
  eventName: string;
  params: Record<string, any>;
  timestamp: number;
  eventType?: string;
}
```

## 🔧 Advanced Integration Patterns

### 1. Firebase Analytics Integration (Recommended)

Instead of logging events in every screen, integrate with Firebase Analytics to automatically capture all events:

```tsx
import analytics from '@react-native-firebase/analytics';
import { logEvent } from 'react-native-event-logger';

// Create a unified analytics function
const trackEvent = (eventName: string, params: any, eventType: string) => {
  // Send to Firebase
  analytics().logEvent(eventName, params);
  
  // Log to debug screen (only in development)
  if (!Prod) {
    logEvent(eventName, params, eventType);
  }
};

// Usage - now you only need to call this function
trackEvent('event_name', { value:'event_value' }, 'event_type');
```

### 3. Analytics Service Pattern

Create a centralized analytics service:

```tsx
// services/analytics.ts
import analytics from '@react-native-firebase/analytics';
import { logEvent } from 'react-native-event-logger';

class AnalyticsService {
  private static instance: AnalyticsService;
  
  static getInstance() {
    if (!AnalyticsService.instance) {
      AnalyticsService.instance = new AnalyticsService();
    }
    return AnalyticsService.instance;
  }
  
  track(eventName: string, params: any, eventType: string = 'firebase') {
    // Send to Firebase
    analytics().logEvent(eventName, params);
    
    // Log to debug screen
    if (!Prod) {
      logEvent(eventName, params, eventType);
    }
  }
  
  trackScreen(screenName: string, params: any = {}) {
    this.track('screen_view', { screen_name: screenName, ...params }, 'screen_view');
  }
  
  trackButton(buttonName: string, params: any = {}) {
    this.track('button_press', { button_name: buttonName, ...params }, 'user_interaction');
  }
  
  trackError(error: Error, params: any = {}) {
    this.track('error', { 
      error_message: error.message, 
      error_stack: error.stack,
      ...params 
    }, 'error');
  }
}

export const analyticsService = AnalyticsService.getInstance();

// Usage in components
analyticsService.trackScreen('ProductScreen');
analyticsService.trackButton('add_to_cart', { product_id: '123' });
```

**Replace Redux logging with this library:**

```tsx
import { logEvent } from 'react-native-event-logger';

const trackGTMEvents = async (name: string, params: CommonEventParams) => {
    // ... existing Firebase logic ...
    
    if (!isProd) {
        const { validName, validParams, errorMsg }: ValidatedEvent = validateFirebaseEvent(name, {
            ...commonUserInfo,
            ...params,
        });

        // Replace Redux dispatch with this library
        logEvent(validName, validParams, 'firebase');
        
        // Validation errors are automatically displayed in the debug screen
        // No need to manually handle errorMsg
    }

    FirebaseAnalytics().logEvent(name, { ...commonUserInfo, ...params });
};
```

**Benefits:**
- ✅ Beautiful debug UI instead of Redux logs
- ✅ Real-time validation error display
- ✅ Search and filter capabilities
- ✅ Expandable event details
- ✅ No need to manage Redux state for events

## 🔍 Validation Rules

### Event Names
- Must be 1-40 characters
- Alphanumeric + underscore only
- Cannot start with restricted prefixes (`firebase_`, `google_`, `ga_`, `AD_`)
- Cannot use reserved Firebase event names

### Parameters
- Maximum 100 parameters per event
- Maximum 100 characters per parameter value
- Parameter names: 1-40 characters, alphanumeric + underscore
- Supported types: string, boolean, number, null

### 8. Production Considerations

```tsx
// ✅ Good - conditional logging
const logEventSafely = (eventName: string, params: any, eventType: string) => {
  // Only log in development or when explicitly enabled
  if (!Prod || process.env.ENABLE_EVENT_LOGGING) {
    logEvent(eventName, params, eventType);
  }
};

// ✅ Better - with error handling
const logEventWithErrorHandling = (eventName: string, params: any, eventType: string) => {
  try {
    if (!Prod) {
      logEvent(eventName, params, eventType);
    }
  } catch (error) {
    console.warn('Failed to log event:', error);
  }
};
```

## 🧪 Development

### Running the Example App

```bash
cd eventlogger
npm install
npm run ios
# or
npm run android
```

### Testing

```bash
npm test
```

## 📦 Publishing

### Build Library

```bash
npm run build
```

### Publish to NPM

```bash
npm publish
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

If you encounter any issues or have questions, please:

1. Check the [Issues](https://github.com/your-repo/react-native-event-logger/issues) page
2. Create a new issue with detailed information
3. Include code examples and error messages

---

**Made with ❤️ for React Native developers**