XG Nova SDK for React Native

A powerful and flexible feature flags and analytics SDK for React Native applications.

Features

• 🚀 Feature Flags: Real-time feature flag management
• 📊 Analytics: Event tracking and user analytics
• 📈 Automatic Flag Tracking: Auto-track feature flag usage for analytics
• 🔧 Pluggable Architecture: Works with any React Native setup
• 💾 Smart Storage: Automatic fallback between SecureStore and AsyncStorage
• 🌐 Network Resilience: Automatic retry and offline support
• ⚡ React Hooks: Easy integration with React components

Installation

npm install xg-nova-sdk

Peer Dependencies

The SDK works with any React Native setup, but you may want to install these optional dependencies for enhanced functionality:

# For React Native projects
npm install @react-native-async-storage/async-storage

# For Expo projects (additional secure storage)
npm install expo-secure-store

# For network connectivity monitoring (optional)
npm install @react-native-community/netinfo

Basic Usage

1. Initialize the SDK

import { XGFeatureFlags } from 'xg-nova-sdk';

// Basic initialization
await XGFeatureFlags.initialise('your-api-key');

// With options
await XGFeatureFlags.initialise('your-api-key', {
  debug: true,
  refreshInterval: 30000, // 30 seconds
  flushAt: 20, // Flush events when queue reaches 20
  autoTrackFeatureFlagCalls: true, // Automatically track flag usage (default: true)
});

2. Register a User

await XGFeatureFlags.register('user-123', {
  email: '[email protected]',
  plan: 'premium',
});

3. Use Feature Flags

// Get a feature flag value
const flag = XGFeatureFlags.getFlag('new-feature', false);
console.log(flag.value); // true/false
console.log(flag.data);  // Additional payload data

// In React components with hooks
import { useFeatureFlag } from 'xg-nova-sdk';

function MyComponent() {
  const { value: showNewUI } = useFeatureFlag('new-ui', false);
  
  return showNewUI ? <NewUI /> : <OldUI />;
}

4. Track Events

// Track user events
XGFeatureFlags.trace('button_clicked', {
  button_name: 'subscribe',
  screen: 'pricing',
});

Automatic Feature Flag Tracking

The SDK automatically tracks feature flag usage by sending $feature_flag_called events to PostHog whenever a feature flag is accessed. This provides valuable analytics about which flags are being used and how often.

How it works:

• Automatic: Sends $feature_flag_called event when getFlag() or useFeatureFlag() is called
• Once per session: Each flag is tracked only once per user session to avoid spam
• PostHog compatible: Follows PostHog's recommended event structure
• Configurable: Can be disabled if needed

Event properties:

{
  event: "$feature_flag_called",
  properties: {
    "$feature_flag": "feature-flag-key",
    "$feature_flag_response": "variant-name"
  }
}

Disable automatic tracking:

await XGFeatureFlags.initialise('your-api-key', {
  autoTrackFeatureFlagCalls: false, // Disable automatic tracking
});

Advanced Usage

Custom Storage Provider

If you need to use a different storage solution:

import { XGFeatureFlags, StorageProvider } from 'xg-nova-sdk';

const customStorage: StorageProvider = {
  async get(key: string) {
    // Your custom get implementation
    return await MyCustomStorage.getItem(key);
  },
  async set(key: string, value: string) {
    // Your custom set implementation
    await MyCustomStorage.setItem(key, value);
  },
  async del(key: string) {
    // Your custom delete implementation
    await MyCustomStorage.removeItem(key);
  },
};

await XGFeatureFlags.initialise('your-api-key', {
  storageProvider: customStorage,
});

Custom Network Monitoring

For custom app state and network connectivity monitoring:

import { XGFeatureFlags, NetworkMonitor } from 'xg-nova-sdk';

const customNetworkMonitor: NetworkMonitor = {
  onAppStateChange: (callback) => {
    // Your custom app state monitoring
    MyAppState.addEventListener('change', callback);
  },
  onNetworkStateChange: (callback) => {
    // Your custom network state monitoring
    MyNetInfo.addEventListener((state) => {
      callback(state.isConnected);
    });
  },
};

await XGFeatureFlags.initialise('your-api-key', {
  networkMonitor: customNetworkMonitor,
});

Configuration Options

interface InitOptions {
  /** Override proxy base if you self-host (default: XG cloud) */
  proxyBaseUrl?: string;
  
  /** Enable verbose console logs in dev builds */
  debug?: boolean;
  
  /** Refresh interval in milliseconds (default: 30000) */
  refreshInterval?: number;
  
  /** Flush events when queue reaches this number (default: 20) */
  flushAt?: number;
  
  /** Automatically track feature flag usage (default: true) */
  autoTrackFeatureFlagCalls?: boolean;
  
  /** Custom storage provider */
  storageProvider?: StorageProvider;
  
  /** Network monitoring provider */
  networkMonitor?: NetworkMonitor;
}

Compatibility

React Native CLI Projects

Works out of the box with React Native AsyncStorage:

npm install @react-native-async-storage/async-storage

Expo Projects

Automatically uses Expo SecureStore when available:

expo install expo-secure-store @react-native-async-storage/async-storage

Custom React Native Setups

The SDK gracefully handles missing dependencies and provides pluggable interfaces for custom implementations.

Storage Fallback Strategy

The SDK uses an intelligent storage fallback strategy:

1. Expo SecureStore (if available and data ≤ 2048 bytes)
2. React Native AsyncStorage (fallback)
3. Custom Storage Provider (if provided)
4. No-op (with warnings, if no storage available)

Error Handling

The SDK includes comprehensive error handling:

• Network requests are retried with exponential backoff
• Storage operations fail gracefully
• Missing dependencies are handled with warnings
• Events are queued and persisted across app restarts

TypeScript Support

Full TypeScript support with comprehensive type definitions:

// Typed feature flags
const { value } = useFeatureFlag<boolean>('feature-enabled', false);
const { value: config } = useFeatureFlag<{theme: string}>('app-config', {theme: 'light'});

Building from Source

# Clone the repository
git clone <repo-url>
cd xg-nova-sdk

# Install dependencies
npm install

# Build
npm run build

License

MIT License - see LICENSE file for details.