@datafast/react-native

DataFast analytics SDK for React Native and Expo apps.

Installation

# Install the SDK
npm install @datafast/react-native @datafast/core

# Install required peer dependency
npm install @react-native-async-storage/async-storage

# Install optional peer dependencies (recommended)
npm install @react-native-community/netinfo  # For offline support

For Expo:

npx expo install @react-native-async-storage/async-storage @react-native-community/netinfo expo-device expo-constants

Quick Start

import { initDataFast } from '@datafast/react-native';

// Initialize once at app startup
const datafast = await initDataFast({
  appId: 'your-datafast-app-id',  // From DataFast dashboard
  domain: 'com.example.myapp',     // Your app bundle ID
  debug: true,                     // Enable for development
});

// Track screen views
datafast.trackScreen('HomeScreen');

// Track custom events
datafast.track('button_click', { button: 'signup' });

// Identify users (after login)
datafast.identify('user_123', {
  name: 'John Doe',
  email: '[email protected]'
});

// Track payments
datafast.trackPayment({ email: '[email protected]' });

React Navigation Integration

Option 1: Using onStateChange

import { NavigationContainer } from '@react-navigation/native';
import { initDataFast, useDataFastNavigation } from '@datafast/react-native';
import { useEffect, useState } from 'react';

function App() {
  const [datafast, setDatafast] = useState(null);

  useEffect(() => {
    initDataFast({
      appId: 'your-app-id',
      domain: 'com.example.myapp',
    }).then(setDatafast);
  }, []);

  const onStateChange = useDataFastNavigation(datafast);

  return (
    <NavigationContainer onStateChange={onStateChange}>
      <RootNavigator />
    </NavigationContainer>
  );
}

Option 2: Manual Screen Tracking

import { useDataFastScreen } from '@datafast/react-native';

function ProfileScreen({ datafast }) {
  // Tracks screen view when component mounts
  useDataFastScreen(datafast, 'ProfileScreen');

  return <View>...</View>;
}

API Reference

initDataFast(config)

Initialize the SDK with automatic adapter detection.

const datafast = await initDataFast({
  appId: string,           // Required: Your DataFast app ID
  domain: string,          // Required: App bundle ID (e.g., "com.example.myapp")
  platform?: 'ios' | 'android',  // Auto-detected
  appVersion?: string,     // Auto-detected from Expo Constants
  apiUrl?: string,         // Custom API endpoint
  debug?: boolean,         // Enable debug logging
  flushInterval?: number,  // Flush interval in ms (default: 30000)
  maxQueueSize?: number,   // Max queued events (default: 20)
});

datafast.trackScreen(screenName)

Track a screen view. This is the mobile equivalent of a pageview.

datafast.trackScreen('HomeScreen');
datafast.trackScreen('Settings/Account');  // Nested screens

datafast.track(eventName, properties?)

Track a custom event.

datafast.track('button_click', {
  button: 'signup',
  location: 'header'
});

Constraints:

• Event name: lowercase alphanumeric + _ or -, max 64 chars
• Max 10 properties per event
• Property names: max 64 chars
• Property values: max 255 chars

datafast.identify(userId, properties?)

Identify a user (call after login/signup).

datafast.identify('user_123', {
  name: 'John Doe',
  email: '[email protected]',
  plan: 'premium',
});

datafast.trackPayment(data)

Track a payment/conversion event.

datafast.trackPayment({
  email: '[email protected]',
  amount: 99,
  currency: 'USD',
});

datafast.flush()

Immediately flush all queued events.

await datafast.flush();

datafast.reset()

Reset visitor identity (e.g., on logout).

await datafast.reset();

datafast.optOut() / datafast.optIn()

Handle user privacy preferences.

// User opts out of tracking
await datafast.optOut();

// User opts back in
await datafast.optIn();
await datafast.init(config); // Re-initialize

Offline Support

Events are automatically queued when offline and sent when connectivity is restored. This requires @react-native-community/netinfo to be installed.

How Data Appears in DataFast

Mobile events use this href format in the DataFast dashboard:

datafast://ios/HomeScreen
datafast://android/ProfileScreen

To filter mobile traffic in your dashboard:

• All mobile: href LIKE 'datafast://%'
• iOS only: href LIKE 'datafast://ios/%'
• Android only: href LIKE 'datafast://android/%'

Advanced: Custom Adapters

For non-standard setups, provide your own adapters:

import {
  createDataFastWithAdapters,
  createAsyncStorageAdapter,
  createNetInfoAdapter,
} from '@datafast/react-native';

const datafast = await createDataFastWithAdapters({
  appId: 'your-app-id',
  domain: 'com.example.myapp',
  platform: 'ios',
  storage: createAsyncStorageAdapter(MyCustomStorage),
  network: createNetInfoAdapter(MyNetInfo),
});