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

npm install react-native-event-logger

🎯 Quick Start

1. Wrap Your App

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

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

2. Basic Event Logging

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)

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

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

📚 API Reference

Components

EventTrackerProvider

Wraps your app and provides event tracking context.

<EventTrackerProvider>
  <YourApp />
</EventTrackerProvider>

EventDebugScreen

Displays all logged events with expandable details.

<EventDebugScreen />

Functions

logEvent(eventName, params, eventType?)

Logs an event with the given name and parameters.

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.

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:

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:

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:

// 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:

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

// ✅ 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

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

Testing

npm test

📦 Publishing

Build Library

npm run build

Publish to NPM

npm publish

📄 License

MIT License - see 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 page
2. Create a new issue with detailed information
3. Include code examples and error messages

Made with ❤️ for React Native developers