Prodiax React Native SDK

A comprehensive event tracking SDK for React Native and Expo applications with automatic tracking capabilities.

📦 Installation

Basic Installation

npm install prodiax-mobile-sdk

Required Dependencies

This package requires the following peer dependencies to be installed in your project:

For Expo Projects

# Required for device information and app metadata
npx expo install expo-device expo-application

# Required for automatic screen tracking (optional but recommended)
npx expo install expo-router

For React Native CLI Projects

# Install React Native dependencies
npm install react react-native

# Install Expo modules (if using Expo modules in bare React Native)
npx expo install expo-device expo-application

Complete Installation Example

# Install the main package
npm install prodiax-mobile-sdk

# Install required dependencies for Expo
npx expo install expo-device expo-application expo-router

# Or for React Native CLI
npm install react react-native
npx expo install expo-device expo-application

⚠️ Important Notes

• expo-device: Required for device information (device type, OS, etc.)
• expo-application: Required for app metadata (version, build number, etc.)
• expo-router: Optional but highly recommended for automatic screen tracking
• react & react-native: Required core dependencies

If you don't install these dependencies, you'll see import errors when using the package.

🎯 Why This is Important:

1. Prevents Confusion: Users will know exactly what to install
2. Reduces Support Issues: Clear instructions prevent common installation problems
3. Better User Experience: Users can get started quickly without errors
4. Professional Package: Shows you've thought about the user experience

📝 Additional Recommendations:

1. Add a "Getting Started" section with a complete example
2. Include error messages users might see if dependencies are missing
3. Add a "Common Issues" section in troubleshooting
4. Consider adding a "Migration Guide" if users are upgrading from an older version

This will make your package much more user-friendly and professional! 🚀

Quick Start

1. Wrap your app with ProdiaxTrackingProvider

import { ProdiaxTrackingProvider } from 'prodiax-mobile-sdk';

export default function App() {
  return (
    <ProdiaxTrackingProvider
      config={{
        productId: 'your-product-id',
        debugMode: __DEV__, // Enable debug mode in development
        enableAutomaticScreenTracking: true,
        enableAutomaticAppStateTracking: true,
        enableAutomaticErrorTracking: true,
      }}
    >
      {/* Your app components */}
    </ProdiaxTrackingProvider>
  );
}

2. Use the tracking hook in your components

import { useProdiax } from 'prodiax-mobile-sdk';

export default function MyComponent() {
  const { track, identify } = useProdiax();

  const handleButtonPress = () => {
    track('button_clicked', {
      button_name: 'search_hotels',
      screen: 'home'
    });
  };

  const handleUserLogin = (userId: string) => {
    identify(userId, {
      email: '[email protected]',
      plan: 'premium'
    });
  };

  return (
    <TouchableOpacity onPress={handleButtonPress}>
      <Text>Search Hotels</Text>
    </TouchableOpacity>
  );
}

Configuration Options

interface ProdiaxConfig {
  productId: string;                    // Required: Your product ID
  apiEndpoint?: string;                 // Default: 'https://api.prodiax.com/track'
  environment?: 'development' | 'production'; // Default: 'production'
  debugMode?: boolean;                  // Default: false
  enableAutomaticScreenTracking?: boolean;    // Default: true
  enableAutomaticAppStateTracking?: boolean;  // Default: true
  enableAutomaticErrorTracking?: boolean;     // Default: true
  sessionTimeoutMs?: number;            // Default: 30 minutes
  maxSessionDurationMs?: number;        // Default: 24 hours
  batchSize?: number;                   // Default: 20
  batchIntervalMs?: number;             // Default: 3000ms
}

API Reference

useProdiax Hook

const { track, trackScreen, identify, reset, flush, getSession, getCurrentScreen } = useProdiax();

Methods

• track(eventName, properties?) - Track a custom event
• trackScreen(screenName, screenTitle?, params?) - Track a screen view
• identify(userId, traits?) - Identify a user
• reset() - Reset the SDK state
• flush() - Force send queued events
• getSession() - Get current session info
• getCurrentScreen() - Get current screen info

Automatic Tracking

The SDK automatically tracks:

Screen Views

• Automatically tracks screen changes with Expo Router
• Includes screen name, title, and parameters
• Maintains screen history

App State Changes

• Tracks when app goes to background/foreground
• Measures time spent in each state

Errors

• Captures console errors
• Tracks unhandled promise rejections
• Includes error context and stack traces

Sessions

• Creates new sessions automatically
• Handles session timeouts (30 minutes of inactivity)
• Tracks session duration and event counts

Event Examples

E-commerce Events

// Product view
track('product_viewed', {
  product_id: 'hotel-123',
  product_name: 'Grand Hotel',
  category: 'luxury',
  price: 299
});

// Booking initiated
track('booking_initiated', {
  hotel_id: 'hotel-123',
  check_in: '2024-02-15',
  check_out: '2024-02-17',
  guests: 2,
  total_price: 598
});

// Booking completed
track('booking_completed', {
  booking_id: 'booking-456',
  hotel_id: 'hotel-123',
  payment_method: 'credit_card',
  total_amount: 598
});

User Engagement Events

// Search performed
track('search_performed', {
  search_query: 'Paris hotels',
  filters_applied: ['price', 'rating'],
  results_count: 25
});

// Filter applied
track('filter_applied', {
  filter_type: 'price_range',
  filter_value: '100-200',
  results_count: 12
});

// Favorite added
track('favorite_added', {
  item_type: 'hotel',
  item_id: 'hotel-123',
  item_name: 'Grand Hotel'
});

Privacy & Security

• No PII Collection: The SDK never collects personally identifiable information
• No User Input: Text input values are never tracked
• Anonymous IDs: Uses anonymous identifiers for user tracking
• Secure Transmission: All data is transmitted over HTTPS
• Local Storage: Minimal local storage for session management

Best Practices

1. Wrap Early: Place the provider as high as possible in your component tree
2. Use Meaningful Event Names: Use descriptive, consistent event names
3. Include Context: Add relevant properties to provide context
4. Test in Development: Use debugMode: true to see events in console
5. Handle Errors: The SDK handles network errors gracefully

Troubleshooting

Events not appearing

• Check that productId is correctly set
• Ensure the provider wraps your entire app
• Check network connectivity
• Enable debugMode to see console logs

Performance concerns

• Events are batched automatically for efficiency
• Use flush() sparingly, only when necessary
• The SDK is designed to be lightweight and non-blocking

Import errors

• ✅ Make sure you've installed all required dependencies
• ✅ For Expo: npx expo install expo-device expo-application expo-router
• ✅ For React Native CLI: npm install react react-native
• ✅ Check that your project supports the required Expo modules

📋 Requirements

• React Native >= 0.60.0
• React >= 16.8.0
• Expo >= 40.0.0 (for Expo projects)
• Expo Router >= 2.0.0 (for automatic screen tracking)

Required Dependencies

• expo-device - For device information
• expo-application - For app metadata
• expo-router - For automatic screen tracking (optional but recommended)

License

MIT License - see LICENSE file for details.