# React Native SDK

## @userflux/react-native

UserFlux's React Native SDK - send your mobile app analytics data to the UserFlux platform.

## Getting Started

#### 1. Install the package

```tsx
npm install @userflux/react-native
```

or with Yarn:

```tsx
yarn add @userflux/react-native
```

#### 2. Install peer dependencies

The SDK requires these peer dependencies:

{% code overflow="wrap" %}

```tsx
npm install @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info
```

{% endcode %}

#### 3. Platform-specific setup

**iOS**

```tsx
cd ios && pod install
```

**Android**

No additional setup required for Android.

#### 4. Initialize the SDK

```tsx
import UserFlux from '@userflux/react-native'

// Initialize as early as possible in your app (e.g., in App.js or index.js)
UserFlux.initialize('<YOUR_WRITE_KEY>', {
    autoCapture: ['screen_views', 'app_opens'],
    autoEnrich: true,
    defaultTrackingProperties: {
        environment: 'production',
        app_name: 'MyApp'
    },
    trackSession: true
})
```

### Configuration Options

The `initialize` method accepts the following options:

| Option                      | Type            | Default | Description                                                               |
| --------------------------- | --------------- | ------- | ------------------------------------------------------------------------- |
| `autoCapture`               | `Array<string>` | `[]`    | Events to automatically capture: `'screen_views'`, `'app_opens'`, `'all'` |
| `autoEnrich`                | `boolean`       | `true`  | Automatically enrich events with device and location data                 |
| `defaultTrackingProperties` | `object`        | `{}`    | Properties to include with every event                                    |
| `trackSession`              | `boolean`       | `true`  | Track sessions with unique identifiers                                    |
| `disableUserIdStorage`      | `boolean`       | `false` | Don't persist user ID in AsyncStorage                                     |
| `blockCommonBots`           | `boolean`       | `true`  | Block tracking from emulators/simulators                                  |
| `debugMode`                 | `boolean`       | `false` | Enable debug logging                                                      |

### Core Methods

#### Tracking Events

```tsx
// Track a custom event
await UserFlux.track({
    event: 'purchase_completed',
    properties: {
        product_id: '12345',
        product_name: 'Premium Subscription',
        price: 9.99,
        currency: 'USD'
    }
})

// Track with user ID
await UserFlux.track({
    event: 'button_clicked',
    properties: {
        button_name: 'checkout'
    },
    userId: 'user_123'
})
```

#### Identifying Users

```tsx
// Identify a user with profile attributes
await UserFlux.identify({
    userId: 'user_123',
    properties: {
        email: 'user@example.com',
        name: 'John Doe',
        subscription_plan: 'premium',
        created_at: '2024-01-15'
    }
})
```

#### Screen Tracking

```tsx
// Manual screen tracking
await UserFlux.trackScreenView('HomeScreen', {
    category: 'main_navigation'
})

// Or integrate with React Navigation
import { NavigationContainer } from '@react-navigation/native'

function App() {
    const navigationRef = useRef()

    useEffect(() => {
        UserFlux.setNavigationRef(navigationRef)
    }, [])

    return (
        <NavigationContainer
            ref={navigationRef}
            onStateChange={async () => {
                const currentScreen = navigationRef.current?.getCurrentRoute()?.name
                if (currentScreen) {
                    await UserFlux.trackScreenView(currentScreen)
                }
            }}
        >
            {/* Your app screens */}
        </NavigationContainer>
    )
}
```

### React Navigation Integration

For automatic screen tracking with React Navigation:

```tsx
import { useNavigationContainerRef } from '@react-navigation/native'

function App() {
    const navigationRef = useNavigationContainerRef()
    const routeNameRef = useRef()

    return (
        <NavigationContainer
            ref={navigationRef}
            onReady={() => {
                routeNameRef.current = navigationRef.getCurrentRoute().name
            }}
            onStateChange={async () => {
                const previousRouteName = routeNameRef.current
                const currentRouteName = navigationRef.getCurrentRoute().name

                if (previousRouteName !== currentRouteName) {
                    await UserFlux.trackScreenView(currentRouteName, {
                        previous_screen: previousRouteName
                    })
                }

                routeNameRef.current = currentRouteName
            }}
        >
            {/* Your navigation structure */}
        </NavigationContainer>
    )
}
```

### Batch Tracking

```tsx
// Send multiple events at once
await UserFlux.trackBatch([
    {
        event: 'item_viewed',
        properties: { item_id: '1', category: 'electronics' }
    },
    {
        event: 'item_viewed',
        properties: { item_id: '2', category: 'books' }
    },
    {
        event: 'item_added_to_cart',
        properties: { item_id: '1', quantity: 1 }
    }
])
```

### Session Management

Sessions are automatically managed with a 5-minute timeout. When the app goes to background and returns after 5 minutes, a new session is created.

```tsx
// Get current session ID
const sessionId = UserFlux.getSessionId()

// Sessions automatically refresh on app foreground if expired
```

### User Management

```tsx
// Set user ID (persisted across app launches)
UserFlux.setUserId('user_123')

// Set external ID (e.g., from your CRM)
UserFlux.setExternalId('crm_456')

// Get current user ID
const userId = UserFlux.getUserId()

// Get anonymous ID (device identifier)
const anonymousId = UserFlux.getAnonymousId()

// Reset user (logout)
await UserFlux.reset() // Clears user data and creates new anonymous ID
```

### Default Properties

Update default properties that are sent with every event:

```tsx
UserFlux.updateDefaultTrackingProperties({
    app_version: '2.0.0',
    environment: 'production',
    user_segment: 'premium'
})
```

### Offline Support

Events are automatically queued when the device is offline and sent when connectivity is restored:

```tsx
// Events are queued automatically when offline
await UserFlux.track({
    event: 'offline_action',
    properties: { value: 100 }
})

// Manually flush the queue
await UserFlux.flush()
```

### App Lifecycle Events

Track app lifecycle events:

```tsx
import { AppState } from 'react-native'

AppState.addEventListener('change', (nextAppState) => {
    if (nextAppState === 'background') {
        UserFlux.trackAppBackground()
    } else if (nextAppState === 'active') {
        UserFlux.trackAppOpen()
    }
})
```

### Device Information

The SDK automatically collects device information when `autoEnrich` is enabled:

* Platform (iOS/Android)
* Device model and brand
* OS version
* App version and build number
* Screen dimensions
* Timezone and locale
* Network carrier
* Memory and storage info

### Deep Linking

Track app opens from deep links:

```tsx
import { Linking } from 'react-native'

Linking.getInitialURL().then(url => {
    if (url) {
        UserFlux.track({
            event: 'app_opened_from_deep_link',
            properties: {
                url: url,
                source: parseDeepLinkSource(url)
            }
        })
    }
})
```

### TypeScript Support

The SDK includes TypeScript definitions:

```tsx
import UserFlux, { TrackParameters, IdentifyParameters } from '@userflux/react-native'

const trackParams: TrackParameters = {
    event: 'purchase',
    properties: {
        amount: 99.99
    },
    userId: 'user_123'
}

await UserFlux.track(trackParams)
```

### Best Practices

1. **Initialize Early**: Call `UserFlux.initialize()` as early as possible in your app lifecycle
2. **User Identification**: Call `identify()` as soon as you have user information
3. **Screen Tracking**: Integrate with your navigation solution for automatic screen tracking
4. **Batch Events**: Use `trackBatch()` when tracking multiple related events
5. **Cleanup**: Call `UserFlux.cleanup()` when your app unmounts (if needed)

### Troubleshooting

#### Events not being sent

1. Check that you've initialized the SDK with a valid API key
2. Verify network connectivity
3. Enable debug mode to see logs: `{ debugMode: true }`
4. Check that events are not being blocked by emulator detection

#### Storage issues

* The SDK uses AsyncStorage for persistence
* Ensure AsyncStorage is properly installed and linked
* Storage is automatically cleared on `reset()`

#### Session management

* Sessions timeout after 5 minutes of inactivity
* New sessions are created when the app returns from background after timeout
* Session IDs are not persisted between app launches


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://userflux.gitbook.io/userflux-docs/sdks/react-native-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.