MostlyGoodMetrics React Native SDK

A lightweight React Native SDK for tracking analytics events with MostlyGoodMetrics.

Requirements

• React Native 0.71+
• Expo SDK 49+ (if using Expo)

Installation

Expo (Recommended)

npm install @mostly-good-metrics/react-native

That's it! Expo includes AsyncStorage by default, so events persist across app restarts.

Bare React Native

npm install @mostly-good-metrics/react-native @react-native-async-storage/async-storage
cd ios && pod install

Note: AsyncStorage is optional. Without it, events are stored in memory only (lost on app restart).

Quick Start

1. Initialize the SDK

Initialize once at app startup:

import MostlyGoodMetrics from '@mostly-good-metrics/react-native';

MostlyGoodMetrics.configure('mgm_proj_your_api_key');

2. Track Events

// Simple event
MostlyGoodMetrics.track('button_clicked');

// Event with properties
MostlyGoodMetrics.track('purchase_completed', {
  product_id: 'SKU123',
  price: 29.99,
  currency: 'USD',
});

3. Identify Users

// Set user identity
MostlyGoodMetrics.identify('user_123');

// Reset identity (e.g., on logout)
MostlyGoodMetrics.resetIdentity();

That's it! Events are automatically batched and sent.

Configuration Options

For more control, pass a configuration object:

import { version } from './package.json'; // Or use expo-constants

MostlyGoodMetrics.configure('mgm_proj_your_api_key', {
  baseURL: 'https://mostlygoodmetrics.com',
  environment: 'production',
  appVersion: version, // Required for install/update tracking
  maxBatchSize: 100,
  flushInterval: 30,
  maxStoredEvents: 10000,
  enableDebugLogging: __DEV__,
  trackAppLifecycleEvents: true,
});

| Option | Default | Description | |--------|---------|-------------| | baseURL | https://mostlygoodmetrics.com | API endpoint | | environment | "production" | Environment name | | appVersion | - | App version string (required for install/update tracking) | | maxBatchSize | 100 | Events per batch (1-1000) | | flushInterval | 30 | Auto-flush interval in seconds | | maxStoredEvents | 10000 | Max cached events | | enableDebugLogging | false | Enable console output | | trackAppLifecycleEvents | true | Auto-track lifecycle events |

Automatic Events

When trackAppLifecycleEvents is enabled (default), the SDK automatically tracks:

| Event | When | Properties | |-------|------|------------| | $app_installed | First launch after install | $version | | $app_updated | First launch after version change | $version, $previous_version | | $app_opened | App became active (foreground) | - | | $app_backgrounded | App resigned active (background) | - |

Automatic Properties

The SDK automatically includes these properties with every event:

| Property | Description | |----------|-------------| | $device_type | Device type (phone, tablet) | | $storage_type | Storage type (persistent or memory) |

Additionally, osVersion and appVersion (if configured) are included at the event level.

Event Naming

Event names must:

• Start with a letter (or $ for system events)
• Contain only alphanumeric characters and underscores
• Be 255 characters or less

// Valid
MostlyGoodMetrics.track('button_clicked');
MostlyGoodMetrics.track('PurchaseCompleted');
MostlyGoodMetrics.track('step_1_completed');

// Invalid (will be ignored)
MostlyGoodMetrics.track('123_event');      // starts with number
MostlyGoodMetrics.track('event-name');     // contains hyphen
MostlyGoodMetrics.track('event name');     // contains space

Properties

Events support various property types:

MostlyGoodMetrics.track('checkout', {
  string_prop: 'value',
  int_prop: 42,
  double_prop: 3.14,
  bool_prop: true,
  null_prop: null,
  list_prop: ['a', 'b', 'c'],
  nested: {
    key: 'value',
  },
});

Limits:

• String values: truncated to 1000 characters
• Nesting depth: max 3 levels
• Total properties size: max 10KB

Manual Flush

Events are automatically flushed periodically and when the app backgrounds. You can also trigger a manual flush:

MostlyGoodMetrics.flush();

To check pending events:

const count = await MostlyGoodMetrics.getPendingEventCount();
console.log(`${count} events pending`);

Automatic Behavior

The SDK automatically:

• Persists events to AsyncStorage, surviving app restarts
• Batches events for efficient network usage
• Flushes on interval (default: every 30 seconds)
• Flushes on background when the app goes to background
• Retries on failure for network errors (events are preserved)
• Persists user ID across app launches
• Generates session IDs per app launch

Debug Logging

Enable debug logging to see SDK activity:

MostlyGoodMetrics.configure('mgm_proj_your_api_key', {
  enableDebugLogging: true,
});

Output example:

[MostlyGoodMetrics] Configuring with options: {...}
[MostlyGoodMetrics] Setting up lifecycle tracking
[MostlyGoodMetrics] App opened (foreground)
[MostlyGoodMetrics] Flushing events

Running the Example

cd example
npm install

For iOS:

cd ios && pod install && cd ..
npm run ios

For Android:

npm run android

License

MIT