PostHog

https://posthog.com/docs/libraries/react-native
Admin
PostHog is an open-source Product OS platform providing product analytics, session replay, feature...
Tokens:19,069
Snippets:174
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install iOS dependencies with CocoaPods

Source: https://posthog.com/docs/libraries/react-native

Run pod install in the ios directory to resolve the plugin and posthog-ios via CocoaPods.

```bash
cd ios
pod install
```

--------------------------------

### PostHog React Native SDK setup differences across V1, V2, V3, and V4

Source: https://posthog.com/docs/libraries/react-native

Shows the deprecated V1 setup using PostHog.setup, the V2 setup using Posthog.initAsync, and the V3/V4 setup using new PostHog. Highlights removed options like captureDeepLinks, android/iOS config, and captureMode, and notes that captureAppLifecycleEvents is enabled by default since 4.39.0. Also shows replacement methods setPersonPropertiesForFlags and setGroupPropertiesForFlags.

```jsx
// DEPRECATED V1 Setup

import PostHog from 'posthog-react-native'

await PostHog.setup('<ph_project_token>', {
    // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
    host: 'https://us.i.posthog.com',
    captureApplicationLifecycleEvents: false, // Replaced by 'PostHogProvider'
    captureDeepLinks: false, // No longer supported
    recordScreenViews: false, // Replaced by 'PostHogProvider' supporting @react-navigation/native
    flushInterval: 30, // Stays the same
    flushAt: 20, // Stays the same
    android: {...}, // No longer needed
    iOS: {...}, // No longer needed
})

PostHog.capture("foo")


// V2 Setup difference
import PostHog from 'posthog-react-native'

const posthog = await Posthog.initAsync('<ph_project_token>', {
    // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
    host: 'https://us.i.posthog.com',
    // Add any other options here.
})

// Use created instance rather than the PostHog class
posthog.capture("foo")

// V3 Setup difference
import PostHog from 'posthog-react-native'

const posthog = new PostHog('<ph_project_token>', {
    // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
    host: 'https://us.i.posthog.com',
    // Add any other options here.
})

// Use created instance rather than the PostHog class
posthog.capture("foo")

// V4 Setup difference
import PostHog from 'posthog-react-native'

const posthog = new PostHog('<ph_project_token>', {
    // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
    host: 'https://us.i.posthog.com',
    // captureAppLifecycleEvents is enabled by default since version 4.39.0 (previously named `captureNativeAppLifecycleEvents` or `autocapture={{ captureLifecycleEvents: true }}`)
    // captureMode: 'json', // No longer supported
    // maskPhotoLibraryImages: true, // No longer supported
})

posthog.setPersonPropertiesForFlags(...) // instead of `personProperties`
posthog.setGroupPropertiesForFlags(...) // instead of `groupProperties`
```

--------------------------------

### Install posthog-react-native for Expo apps

Source: https://posthog.com/docs/libraries/react-native

Run this command in an Expo project to install posthog-react-native and its required peer dependencies (expo-file-system, expo-application, expo-device, expo-localization).

```bash
npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localization
```

--------------------------------

### Install posthog-react-native for React Native apps

Source: https://posthog.com/docs/libraries/react-native

Use either yarn or npm to install posthog-react-native and its required peer dependencies (@react-native-async-storage/async-storage, react-native-device-info, react-native-localize).

```bash
yarn add posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize
# or
npm i -s posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize
```

--------------------------------

### Add dynamic frameworks to Podfile for hybrid SPM path

Source: https://posthog.com/docs/libraries/react-native

Add this line to your ios/Podfile to use dynamic frameworks, which is required for the hybrid CocoaPods + Swift Package Manager path. This must be done before running pod install.

```ruby
use_frameworks! :linkage => :dynamic
```

--------------------------------

### Manually flush the PostHog queue

Source: https://posthog.com/docs/libraries/react-native

Starts sending queued events immediately. If a flush is already in progress, it returns a promise for the existing flush. Flushing is best-effort and asynchronous, so it does not guarantee delivery.

```javascript
await posthog.flush()
```

--------------------------------

### Convert to full Swift Package Manager with npx react-native spm add

Source: https://posthog.com/docs/libraries/react-native

Run this command from the ios directory to convert the project to full Swift Package Manager integration. The --deintegrate option removes the complete CocoaPods integration. Do not run pod install after this. Requires React Native's experimental CocoaPods-free iOS integration and that all native dependencies support it.

```bash
npx react-native spm add --deintegrate --yes
```

--------------------------------

### Set super properties with posthog.register

Source: https://posthog.com/docs/libraries/react-native

Registers super properties that are sent with every capture call. The example sets 'icecream pref' and 'team_id'. These properties persist across sessions and are included in all subsequent events.

```javascript
posthog.register({
    'icecream pref': 'vanilla',
    team_id: 22,
})
```

--------------------------------

### Use usePostHog hook to capture events

Source: https://posthog.com/docs/libraries/react-native

Inside a component, call usePostHog() to get the client and capture events, e.g., in a useEffect.

```jsx
const MyComponent = () => {
    const posthog = usePostHog()

    useEffect(() => {
        posthog.capture("event_name")
    }, [posthog])
}
```

--------------------------------

### Error handling for feature flag operations

Source: https://posthog.com/docs/libraries/react-native

Wrap PostHog SDK methods in a try-catch to handle errors during feature flag operations. The example shows a `handleFeatureFlag` function that logs the flag status and rethrows errors, with a usage example that implements fallback logic.

```jsx
function handleFeatureFlag(client, flagKey, distinctId) {
    try {
        const isEnabled = client.isFeatureEnabled(flagKey, distinctId);
        console.log(`Feature flag '${flagKey}' for user '${distinctId}' is ${isEnabled ? 'enabled' : 'disabled'}`);
        return isEnabled;
    } catch (error) {
        console.error(`Error fetching feature flag '${flagKey}': ${error.message}`);
        // Optionally, you can return a default value or throw the error
        // return false; // Default to disabled
        throw error;
    }
}

// Usage example
try {
    const flagEnabled = handleFeatureFlag(client, 'new-feature', 'user-123');
    if (flagEnabled) {
        // Implement new feature logic
    } else {
        // Implement old feature logic
    }
} catch (error) {
    // Handle the error at a higher level
    console.error('Feature flag check failed, using default behavior');
    // Implement fallback logic
}
```

--------------------------------

### Manually capture screen view with posthog.screen

Source: https://posthog.com/docs/libraries/react-native

Calls the `screen` method within the `trackScreenView` method to manually capture screen views when using @react-navigation/native v7 or higher. Uses `usePostHog` hook to get the posthog instance.

```jsx
const posthog = usePostHog() // use the usePostHog hook if using the PostHogProvider or your own custom posthog instance
// you can read the params from `getCurrentRoute()`
posthog.screen(currentRouteName, params)
```

--------------------------------

### reloadFeatureFlagsAsync

Source: https://posthog.com/docs/libraries/react-native

Manually trigger a refresh of feature flags and get the refreshed flags.

```APIDOC
## reloadFeatureFlagsAsync

### Description
Manually triggers a refresh of feature flags. Returns a promise that resolves with the refreshed flags.

### Usage
```jsx
posthog.reloadFeatureFlagsAsync().then((refreshedFlags) => console.log(refreshedFlags))
```
```

--------------------------------

### Customize exception capture with before_send callback

Source: https://posthog.com/docs/libraries/react-native

Use the before_send callback to modify, filter, or suppress exception events before they are sent to PostHog. This example adds custom properties, overrides the exception fingerprint, and drops events of type 'IgnoredError'. The callback can also be used to sample or filter other event types.

```jsx
const posthog = new PostHog('<ph_project_token>', {
  host: 'https://us.i.posthog.com',
  before_send: (event) => {
    if (event.event === '$exception') {
      const exceptionList = event.properties?.['$exception_list'] || []
      const exception = exceptionList.length > 0 ? exceptionList[0] : null

      if (exception) {
        // Add custom properties
        event.properties['custom_property'] = 'custom_value'

        // Override fingerprint for custom grouping
        event.properties['$exception_fingerprint'] = 'MyCustomGroup'
      }

      // Suppress specific exception types
      if (exception?.['$exception_type'] === 'IgnoredError') {
        return null // Drop the event
      }
    }
    return event
  },
})
```

--------------------------------

### Force refresh feature flags on app start

Source: https://posthog.com/docs/libraries/react-native

Use `posthog.reloadFeatureFlagsAsync()` to force a refresh of feature flag values, ensuring fresh values are fetched from the API. This is useful to avoid stale cached values for inactive users.

```jsx
// Force refresh on app start
await posthog.reloadFeatureFlagsAsync()
```

--------------------------------

### Set up PostHogProvider in App.js

Source: https://posthog.com/docs/libraries/react-native

Wrap your app with PostHogProvider, passing your project API key and host. This enables autocapture and provides the PostHog client via Context API.

```jsx
// App.(js|ts)
import { usePostHog, PostHogProvider } from 'posthog-react-native'
...

export function MyApp() {
    return (
        <PostHogProvider apiKey="<ph_project_token>" options={{
            // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
            host: 'https://us.i.posthog.com',
        }}>
            <MyComponent />
        </PostHogProvider>
    )
}
```

--------------------------------

### Wrap screen and initialize navigation tracking for react-native-navigation

Source: https://posthog.com/docs/libraries/react-native

Wraps a screen with SharedPostHogProvider and registers it with react-native-navigation, then initializes screen tracking with `posthog.initReactNativeNavigation`.

```jsx
export const MyScreen = () => {
  return (
    <SharedPostHogProvider>
      <View>
        ...
      </View>
    </SharedPostHogProvider>
  );
};

Navigation.registerComponent('Screen', () => MyScreen);

Navigation.events().registerAppLaunchedListener(async () => {
  posthog.initReactNativeNavigation({
    navigation: {
      // (Optional) Set the name based on the route. Defaults to the route name.
      routeToName: (name, properties) => name,
      // (Optional) Tracks all passProps as properties. Defaults to undefined
      routeToProperties: (name, properties) => properties,
    },
    captureScreens: true,
  });
});
```

--------------------------------

### Configure flushAt and flushInterval in PostHog constructor

Source: https://posthog.com/docs/libraries/react-native

Sets the number of events to queue before flushing (flushAt) and the flush interval in milliseconds (flushInterval). Defaults are 20 and 10000 respectively. Setting flushAt to 1 sends events immediately but uses more battery.

```javascript
const posthog = new PostHog('<ph_project_token>', {
  flushAt: 20,
  flushInterval: 10000,
})
```

--------------------------------

### Reload feature flags with reloadFeatureFlagsAsync

Source: https://posthog.com/docs/libraries/react-native

Manually trigger a refresh of feature flags and get the refreshed flags in a promise.

```jsx
posthog.reloadFeatureFlagsAsync().then((refreshedFlags) => console.log(refreshedFlags))
```

--------------------------------

### Capture event with properties

Source: https://posthog.com/docs/libraries/react-native

Sends a custom event with additional properties (login_type and is_free_trial) using the `posthog.capture` method.

```jsx
posthog.capture('user_signed_up', {
    login_type: "email",
    is_free_trial: true
})
```

--------------------------------

### Remove a super property with posthog.unregister

Source: https://posthog.com/docs/libraries/react-native

Stops sending a specific super property by unregistering it. The example removes 'icecream pref'. For logout, consider posthog.reset() instead.

```javascript
posthog.unregister('icecream pref'),
```

--------------------------------

### Bootstrap feature flags in PostHogProvider options

Source: https://posthog.com/docs/libraries/react-native

Pass bootstrap in the initialization options to seed identity and flag values, making them available immediately. After the SDK fetches flags, it uses those instead of bootstrapped ones.

```jsx
<PostHogProvider
    apiKey="<ph_project_token>"
    options={{
        host: 'https://us.i.posthog.com',
        bootstrap: {
            distinctId: 'distinct_id_of_your_user',
            isIdentifiedId: true,
            featureFlags: {
                'flag-1': true,
                'variant-flag': 'control',
            },
        },
    }}
>
    <MyComponent />
</PostHogProvider>
```

--------------------------------

### Configure autocapture options in PostHogProvider

Source: https://posthog.com/docs/libraries/react-native

Configure autocapture behavior in PostHogProvider. Touch capture is disabled by default, screen capture is enabled by default. Options include captureTouches, captureScreens, ignoreLabels, customLabelProp, maxElementsCaptured, noCaptureProp, propsToCapture, and navigation callbacks for customizing screen tracking.

```jsx
<PostHogProvider apiKey="<ph_project_token>" autocapture={{
    captureTouches: true, // Disabled by default
    captureScreens: true, // Enabled by default
    ignoreLabels: [], // Any labels here will be ignored from the stack in touch events
    customLabelProp: "ph-label",
    maxElementsCaptured: 20,
    noCaptureProp: "ph-no-capture",
    propsToCapture: ["testID"], // Limit which props are captured. By default, identifiers and text content are captured.

    navigation: {
        // By default, only the screen name is tracked but it is possible to track the
        // params or modify the name by intercepting the autocapture like so
        routeToName: (name, params) => {
            if (params.id) return `${name}/${params.id}`
            return name
        },
        routeToProperties: (name, params) => {
            if (name === "SensitiveScreen") return undefined
            return params
        },
    },
}}>
    ...
</PostHogProvider>
```

--------------------------------

### Initialize PostHog without provider in posthog.ts

Source: https://posthog.com/docs/libraries/react-native

Create a standalone PostHog instance in its own file, exporting it for import elsewhere.

```jsx
import PostHog from 'posthog-react-native'

export const posthog = new PostHog('<ph_project_token>', {
  // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
  host: 'https://us.i.posthog.com'
})
```

--------------------------------

### Manually capture screen view with posthog.screen

Source: https://posthog.com/docs/libraries/react-native

Manually captures a screen view by calling `posthog.screen()` with a name and optional properties object.

```javascript
posthog.screen('dashboard', {
    background: 'blue',
    hero: 'superhog',
})
```

--------------------------------

### Filter autocaptured screens with before_send in PostHogProvider

Source: https://posthog.com/docs/libraries/react-native

Configure `before_send` in the provider's `options` prop to drop `$screen` events for screens in an ignorelist. Return `null` for matching screens to prevent them from being sent. Swap the check for an allowlist to capture only specific screens.

```jsx
const IGNORED_SCREENS = new Set(['Splash', 'Debug'])

<PostHogProvider
    apiKey="<ph_project_token>"
    autocapture={{ captureScreens: true }}
    options={{
        host: 'https://us.i.posthog.com',
        before_send: (event) => {
            if (event?.event === '$screen') {
                const screenName = event.properties?.['$screen_name']
                return IGNORED_SCREENS.has(screenName) ? null : event
            }
            return event
        },
    }}
>
    {/* app */}
</PostHogProvider>
```

--------------------------------

### Use standalone PostHog instance with PostHogProvider

Source: https://posthog.com/docs/libraries/react-native

Pass the standalone instance as the client prop to PostHogProvider.

```jsx
import { posthog } from './posthog'

export function MyApp() {
  return <PostHogProvider client={posthog}>{/* Your app code */}</PostHogProvider>
}
```

--------------------------------

### before_send: Log events instead of sending them

Source: https://posthog.com/docs/libraries/react-native

Shows how to use the before_send hook to log events that would be captured and drop them all.

```APIDOC
## before_send: Log events instead of sending them

### Description
Log events that would be captured for debugging purposes, and drop them all by returning null.

### Method
before_send

### Parameters
- **event** (object) - Required - The event object being sent.

### Request Example
```jsx
const posthog = new PostHog('<ph_project_token>', {
    before_send: (event) => {
        console.log('[PostHog] would send', event?.event, event?.properties)
        return null // drop everything
    },
})
```

### Response
#### Success Response
- Returns null to drop the event.
```

--------------------------------

### Direct Feature Flag Loading

Source: https://posthog.com/docs/libraries/react-native

Methods to load feature flags directly from the posthog instance.

```APIDOC
## Direct Feature Flag Loading

### Description
Load feature flags directly from the `posthog` instance. These methods return `undefined` if flags are not loaded yet or if there was a problem loading.

### Methods
- `posthog.isFeatureEnabled('key')` - Returns boolean indicating if the flag is enabled.
- `posthog.getFeatureFlag('key')` - Returns the flag value (boolean or string for multivariate).
- `posthog.getFeatureFlagResult('key')?.payload` - Returns the flag payload (JsonType or undefined).

### Example
```jsx
posthog.isFeatureEnabled('key-for-your-boolean-flag')
posthog.getFeatureFlag('key-for-your-boolean-flag')
posthog.getFeatureFlag('key-for-your-multivariate-flag')
posthog.getFeatureFlagResult('key-for-your-multivariate-flag')?.payload
```
```

--------------------------------

### Opt In/Out

Source: https://posthog.com/docs/libraries/react-native

Methods to check and control user opt-in/out status for tracking.

```APIDOC
## Opt In/Out

### Description
Control whether tracking is enabled for the user. By default, tracking is enabled unless `defaultOptIn: false` is set. These methods persist the opt-in/out state until changed or reset.

### Methods
- `posthog.optedOut` - Check if the user has opted out.
- `posthog.optIn()` - Opt the user in to tracking.
- `posthog.optOut()` - Opt the user out of tracking.

### Example
```javascript
posthog.optedOut // See if a user has opted out
posthog.optIn() // opt in
posthog.optOut() // opt out
```
```

--------------------------------

### Log events instead of sending them with before_send

Source: https://posthog.com/docs/libraries/react-native

Logs what would be captured and drops all events, useful for debugging.

```jsx
const posthog = new PostHog('<ph_project_token>', {
    before_send: (event) => {
        console.log('[PostHog] would send', event?.event, event?.properties)
        return null // drop everything
    },
})
```

--------------------------------

### Autocapture screen tracking with @react-navigation/native v6 or lower

Source: https://posthog.com/docs/libraries/react-native

Configures PostHogProvider as a child of NavigationContainer to automatically capture screen views when using @react-navigation/native v6 or lower. Requires the `autocapture` property.

```jsx
// App.(js|ts)

import { PostHogProvider } from 'posthog-react-native'
import { NavigationContainer } from '@react-navigation/native'

export function App() {
    return (
        <NavigationContainer>
            <PostHogProvider apiKey="<ph_project_token>" autocapture>
                {/* Rest of app */}
            </PostHogProvider>
        </NavigationContainer>
    )
}
```

--------------------------------

### Use standalone PostHog instance to capture events

Source: https://posthog.com/docs/libraries/react-native

Import the posthog instance and call capture in a component, e.g., in a useEffect.

```jsx
import { posthog } from './posthog'

export function MyApp1() {
    useEffect(() => {
        posthog.capture('event_name')
    }, [])

    return <View>Your app code</View>
}
```

--------------------------------

### Autocapture screen tracking with @react-navigation/native v7 or higher

Source: https://posthog.com/docs/libraries/react-native

Configures PostHogProvider with autocapture options to disable automatic screen capture and enable touch capture for @react-navigation/native v7 or higher. Screen events must be manually captured.

```jsx
// App.(js|ts)

import { PostHogProvider } from 'posthog-react-native'
import { NavigationContainer } from '@react-navigation/native'

// Using `PostHogProvider` is optional, but needed if you want to capture touch events automatically with the `captureTouches` option.
export function App() {
    return (
        <NavigationContainer>
            <PostHogProvider apiKey="<ph_project_token>" autocapture={{
              captureScreens: false, // Screen events are handled differently for v7 and higher
              captureTouches: true,
            }}>
                {/* Rest of app */}
            </PostHogProvider>
        </NavigationContainer>
    )
}
```

--------------------------------

### Manually send a screen capture event with posthog.screen()

Source: https://posthog.com/docs/libraries/react-native

Use the `screen` method to manually send a `$screen` event. This is useful for React Navigation v7 users who must disable automatic capture and call this inside each screen component.

```jsx
posthog.screen('Dashboard', { fromIcon: 'bottom' })
```

--------------------------------

### $set_once: Set person properties only if not already set

Source: https://posthog.com/docs/libraries/react-native

Include the `$set_once` property in a `posthog.capture()` call to set person properties only if the user doesn't already have that property set. This prevents overwriting existing property values.

```javascript
posthog.capture('some_event', { $set_once: { userProperty: 'value' } })
```

--------------------------------

### Supply flags from your own backend with disableRemoteFeatureFlags and updateFlags

Source: https://posthog.com/docs/libraries/react-native

Initialize PostHog with disableRemoteFeatureFlags: true to prevent fetching flags, then push evaluated flags at runtime with updateFlags(). Use bootstrap for values needed at startup. updateFlags replaces flags by default; pass { merge: true } to merge. reset() clears supplied flags, so re-push after identity changes.

```jsx
const posthog = new PostHog('<ph_project_token>', {
  host: 'https://us.i.posthog.com',
  // Don't fetch or evaluate flags on-device – we supply them ourselves.
  disableRemoteFeatureFlags: true,
  // Optional: values that must be available at startup, before updateFlags() runs.
  // Without this, reads return their not-loaded defaults until you push flags.
  bootstrap: {
    featureFlags: { 'my-flag': true },
    featureFlagPayloads: { 'my-flag': { color: 'blue' } },
  },
})

// Later – e.g. after login, once your backend has evaluated flags for this user:
posthog.updateFlags(
  { 'my-flag': true, 'my-variant-flag': 'test' },
  { 'my-flag': { color: 'blue' } }
)

posthog.getFeatureFlag('my-variant-flag') // 'test'
posthog.getFeatureFlagResult('my-flag')?.payload // { color: 'blue' }
```

--------------------------------

### identify with $set_once

Source: https://posthog.com/docs/libraries/react-native

Identifies a user and sets person properties using $set and $set_once, where $set_once only sets the property if it is not already set.

```APIDOC
## identify with $set_once

### Description
Identifies a user and sets person properties. `$set_once` only sets the property if the user doesn't already have that property set.

### Method
identify

### Parameters
- **distinctId** (string) - Required - A unique identifier for the user.
- **properties** (object) - Optional - A dictionary with `$set` and `$set_once` keys.

### Request Example
```jsx
posthog.identify('distinctID',
  {
    $set: {
        email: 'user@posthog.com',
        name: 'My Name'
    },
    $set_once: {
        date_of_first_log_in: '2024-03-01'
    }
  }
)
```

### Response
#### Success Response
- No return value documented.
```

--------------------------------

### Enable debug mode in PostHogProvider options

Source: https://posthog.com/docs/libraries/react-native

Set the debug option to true in the PostHogProvider to enable verbose logs about the SDK's inner workings. Useful when events, feature flags, or surveys are not behaving as expected.

```jsx
<PostHogProvider
    debug={true}
    apiKey="<ph_project_token>"
    options={{
        host: "https://us.i.posthog.com",
    }}
>
```

--------------------------------

### posthog.flush()

Source: https://posthog.com/docs/libraries/react-native

Manually flushes the event queue to send queued events immediately. Returns a promise for the existing flush if one is already in progress.

```APIDOC
## posthog.flush()

### Description
Manually flushes the queue to start sending events immediately instead of waiting for the next batch. If a flush is already in progress, it returns a promise for the existing flush. Flushing is best-effort and asynchronous.

### Method
flush

### Endpoint
posthog.flush()

### Parameters
None

### Request Example
```javascript
await posthog.flush()
```

### Response
#### Success Response
Returns a promise that resolves when the flush is initiated (not when the request finishes).

#### Response Example
```javascript
await posthog.flush()
```
```

--------------------------------

### Call the debug() method

Source: https://posthog.com/docs/libraries/react-native

Call posthog.debug() to enable debug mode programmatically in your code.

```jsx
posthog.debug()
```

--------------------------------

### Enable Swift Package Manager for posthog-ios in Podfile.properties.json

Source: https://posthog.com/docs/libraries/react-native

Add this property to ios/Podfile.properties.json to make the plugin resolve posthog-ios through Swift Package Manager instead of CocoaPods. This setting only affects the plugin; other React Native dependencies still use CocoaPods.

```json
{
  "posthog.useSpm": "true"
}
```

--------------------------------

### Capture custom event with posthog.capture

Source: https://posthog.com/docs/libraries/react-native

Sends a custom event named 'user_signed_up' using the PostHog React Native SDK. Use the `[object] [verb]` naming convention for event names.

```jsx
posthog.capture('user_signed_up')
```

--------------------------------

### Identify user with $set and $set_once

Source: https://posthog.com/docs/libraries/react-native

Sets person properties with $set and only sets properties if not already present with $set_once.

```jsx
posthog.identify('distinctID',
  {
    $set: {
        email: 'user@posthog.com',
        name: 'My Name'
    },
    $set_once: {
        date_of_first_log_in: '2024-03-01'
    }
  }
)
```

--------------------------------

### before_send: Drop a specific event

Source: https://posthog.com/docs/libraries/react-native

Shows how to use the before_send hook to stop a specific event from being sent by returning null.

```APIDOC
## before_send: Drop a specific event

### Description
Stop an internal or debug event from ever being sent by returning null from the before_send hook.

### Method
before_send

### Parameters
- **event** (object) - Required - The event object being sent.

### Request Example
```jsx
const posthog = new PostHog('<ph_project_token>', {
    before_send: (event) => {
        if (event?.event === 'debug_only_event') {
            return null // never send this event
        }
        return event
    },
})
```

### Response
#### Success Response
- Returns the event object to send, or null to drop the event.
```

--------------------------------

### Inspect all feature flags with getAllFeatureFlags

Source: https://posthog.com/docs/libraries/react-native

Iterate over all currently loaded feature flags. Each flag includes key, enabled, variant, and payload. This does not send a $feature_flag_called event.

```jsx
for (const flag of posthog.getAllFeatureFlags()) {
    console.log(flag.key, flag.enabled, flag.variant, flag.payload)
}
```

--------------------------------

### $set: Set person properties on event capture

Source: https://posthog.com/docs/libraries/react-native

Include the `$set` property in a `posthog.capture()` call to set person properties. The properties are set on the user associated with the event.

```javascript
posthog.capture('some_event', { $set: { userProperty: 'value' } })
```

--------------------------------

### Manually capture screen view with expo-router

Source: https://posthog.com/docs/libraries/react-native

Calls the `screen` method within a `useEffect` callback to manually capture screen views when using expo-router.

```jsx
const posthog = usePostHog() // use the usePostHog hook if using the PostHogProvider or your own custom posthog instance
posthog.screen(pathname, params)
```

--------------------------------

### before_send: Redact sensitive properties

Source: https://posthog.com/docs/libraries/react-native

Shows how to use the before_send hook to strip sensitive properties before the event leaves the device.

```APIDOC
## before_send: Redact sensitive properties

### Description
Strip a value from the event properties before it is sent, such as redacting an email address.

### Method
before_send

### Parameters
- **event** (object) - Required - The event object being sent.

### Request Example
```jsx
const posthog = new PostHog('<ph_project_token>', {
    before_send: (event) => {
        if (event?.properties?.email) {
            event.properties.email = '***'
        }
        return event
    },
})
```

### Response
#### Success Response
- Returns the modified event object to send.
```

--------------------------------

### Opt in/out of tracking

Source: https://posthog.com/docs/libraries/react-native

Use these methods to check if a user has opted out, opt in, or opt out of tracking. The choice is persisted until changed or reset.

```javascript
posthog.optedOut // See if a user has opted out
posthog.optIn() // opt in
posthog.optOut() // opt out
```

--------------------------------

### Shared PostHogProvider for react-native-navigation

Source: https://posthog.com/docs/libraries/react-native

Creates a shared PostHogProvider component that wraps screens to capture touches and enable the `usePostHog()` hook when using react-native-navigation. Disables automatic screen capture.

```jsx
import PostHog, { PostHogProvider } from 'posthog-react-native'
import { Navigation } from 'react-native-navigation';

export const posthog = new PostHog('<ph_project_token>');

export const SharedPostHogProvider = (props: any) => {
  return (
    <PostHogProvider client={posthog} autocapture={{
      captureScreens: false, // Screen events are handled differently for react-native-navigation
      captureTouches: true,
    }}>
      {props.children}
    </PostHogProvider>
  );
};
```

--------------------------------

### identify

Source: https://posthog.com/docs/libraries/react-native

Associates events with a specific user by providing a distinct ID and optional properties. This links previously tracked anonymous events to the user.

```APIDOC
## identify

### Description
Associates events with a specific user. This enables full insights into how users interact across sessions, devices, and platforms. When called, all previously tracked anonymous events are linked to the user.

### Method
identify

### Parameters
- **distinctId** (string) - Required - A unique identifier for the user, typically email or database ID.
- **properties** (object) - Optional - A dictionary of key:value pairs to set person properties. Supports `$set` and `$set_once`.

### Request Example
```jsx
posthog.identify('distinctID',
  { // ($set):
      email: 'user@posthog.com',
      name: 'My Name'
  }
)
```

### Response
#### Success Response
- No return value documented.
```

--------------------------------

### Enable native crash autocapture with nativeCrashes and androidNdkCrashes

Source: https://posthog.com/docs/libraries/react-native

Configure PostHog to capture native crashes on both iOS and Android. Set nativeCrashes to true for all native crashes on iOS and Java/Kotlin crashes on Android, and androidNdkCrashes to true for C/C++ NDK crashes on Android 12+. Requires @posthog/react-native-plugin and posthog-react-native 4.78.0+ for NDK support.

```jsx
const posthog = new PostHog('<ph_project_token>', {
  host: 'https://us.i.posthog.com',
  errorTracking: {
    autocapture: {
      nativeCrashes: true,
      androidNdkCrashes: true,
    },
  },
})
```

--------------------------------

### addTracingHeaders

Source: https://posthog.com/docs/libraries/react-native

Configures the PostHog React Native SDK to add tracing headers to network requests matching specified hostnames, connecting them to backend events, errors, and LLM traces.

```APIDOC
## addTracingHeaders

### Description
Use `addTracingHeaders` to connect React Native network requests to backend events, errors, and LLM traces captured by a server-side PostHog SDK. Hostnames are matched exactly. The SDK patches global `fetch` and sends `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` on matching requests when those values are available.

### Method
Configuration option

### Endpoint
N/A (SDK configuration)

### Parameters
#### Configuration
- **addTracingHeaders** (string[]) - Required - List of hostnames to match exactly for adding tracing headers.

### Request Example
```typescript
const posthog = new PostHog('<ph_project_token>', {
  host: 'https://us.i.posthog.com',
  addTracingHeaders: ['api.example.com'],
})
```

### Response
#### Success Response
No direct response. The SDK patches global `fetch` and adds headers `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` to matching requests when available.
```

--------------------------------

### Configure featureFlagsRequestTimeoutMs

Source: https://posthog.com/docs/libraries/react-native

Set the `featureFlagsRequestTimeoutMs` parameter when initializing the PostHog client to control the timeout for flag requests. The default is 10000 milliseconds (10 seconds).

```jsx
export const posthog = new PostHog('<ph_project_token>', {
  // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
  host: 'https://us.i.posthog.com',
  featureFlagsRequestTimeoutMs: 10000 // Time in milliseconds. Default is 10000 (10 seconds).
})
```

--------------------------------

### getAllFeatureFlags

Source: https://posthog.com/docs/libraries/react-native

Inspect all currently loaded feature flags without sending a $feature_flag_called event.

```APIDOC
## getAllFeatureFlags

### Description
Returns all currently loaded feature flags with their `key`, `enabled` state, `variant`, and `payload`. Does not send a `$feature_flag_called` event.

### Usage
```jsx
for (const flag of posthog.getAllFeatureFlags()) {
    console.log(flag.key, flag.enabled, flag.variant, flag.payload)
}
```
```

--------------------------------

### onFeatureFlags Callback

Source: https://posthog.com/docs/libraries/react-native

Register a callback to be invoked when feature flags are loaded.

```APIDOC
## onFeatureFlags

### Description
Registers a callback that is called when the feature flag request finishes, ensuring flags are available.

### Usage
```jsx
posthog.onFeatureFlags((flags) => {
  // feature flags are guaranteed to be available at this point
  if (posthog.isFeatureEnabled('flag-key')) {
    // do something
  }
})
```
```

--------------------------------

### Wait for flags to load with onFeatureFlags

Source: https://posthog.com/docs/libraries/react-native

Use the onFeatureFlags callback to ensure feature flags are loaded before using them, especially on the first visit.

```jsx
posthog.onFeatureFlags((flags) => {
  // feature flags are guaranteed to be available at this point
  if (posthog.isFeatureEnabled('flag-key')) {
    // do something
  }
})
```

--------------------------------

### Identify user with properties

Source: https://posthog.com/docs/libraries/react-native

Associates events with a user using a distinct ID and optional person properties.

```jsx
posthog.identify('distinctID',
  { // ($set):
      email: 'user@posthog.com',
      name: 'My Name'
  }
)
```

--------------------------------

### Configure addTracingHeaders in PostHog React Native

Source: https://posthog.com/docs/libraries/react-native

Use addTracingHeaders to connect React Native network requests to backend events, errors, and LLM traces. Hostnames are matched exactly. The SDK patches global fetch and sends X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID on matching requests when those values are available.

```typescript
const posthog = new PostHog('<ph_project_token>', {
  host: 'https://us.i.posthog.com',
  addTracingHeaders: ['api.example.com'],
})
```

--------------------------------

### Load feature flags directly

Source: https://posthog.com/docs/libraries/react-native

Use these methods to load feature flags directly. They return undefined if not loaded yet or if there was a problem loading. getFeatureFlagResult returns the payload.

```jsx
// Defaults to undefined if not loaded yet or if there was a problem loading
posthog.isFeatureEnabled('key-for-your-boolean-flag')

// Defaults to undefined if not loaded yet or if there was a problem loading
posthog.getFeatureFlag('key-for-your-boolean-flag')

// Multivariant feature flags are returned as a string
posthog.getFeatureFlag('key-for-your-multivariate-flag')

// Optional: fetch the payload (returns 'JsonType' or undefined if not loaded yet or if there was a problem loading)
posthog.getFeatureFlagResult('key-for-your-multivariate-flag')?.payload
```

--------------------------------

### posthog.reset()

Source: https://posthog.com/docs/libraries/react-native

Resets the user's ID and anonymous ID. Typically called after a user logs out.

```APIDOC
## posthog.reset()

### Description
Resets the user's ID and anonymous ID. Usually called right after the user logs out.

### Method
reset

### Endpoint
posthog.reset()

### Parameters
None

### Request Example
```javascript
posthog.reset()
```

### Response
No response body.
```

--------------------------------

### Use PostHogErrorBoundary to capture React rendering errors

Source: https://posthog.com/docs/libraries/react-native

Wrap your app with PostHogErrorBoundary inside PostHogProvider to capture React rendering errors. The fallback prop renders a component when an error occurs, and additionalProperties adds custom properties to the error event. Note: if console capture is also enabled, errors will be captured twice; set console: [] to avoid duplicates.

```jsx
import { PostHogProvider, PostHogErrorBoundary } from 'posthog-react-native'
import { View, Text } from 'react-native'

const App = () => {
  return (
    <PostHogProvider apiKey="<ph_project_token>">
      <PostHogErrorBoundary
        fallback={YourFallbackComponent}
        additionalProperties={{ screen: "home" }}
      >
        <YourApp />
      </PostHogErrorBoundary>
    </PostHogProvider>
  )
}

const YourFallbackComponent = ({ error, componentStack }) => {
  return (
    <View>
      <Text>Something went wrong!</Text>
      <Text>{error instanceof Error ? error.message : String(error)}</Text>
    </View>
  )
}
```

--------------------------------

### Disable PostHog for local development

Source: https://posthog.com/docs/libraries/react-native

Set the disabled option to true in PostHogProvider options to disable PostHog in development or test environments. This allows safe use of usePostHog and capture calls without any actual event sending.

```jsx
// App.(js|ts)
import { usePostHog, PostHogProvider } from 'posthog-react-native'
...

export function MyApp() {
    return (
        <PostHogProvider apiKey="<ph_project_token>" options={{
            // Disable PostHog in development (or whatever other logic you choose)
            disabled: __DEV__,
        }}>
            <MyComponent />
        </PostHogProvider>
    )
}

const MyComponent = () => {
    const posthog = usePostHog()

    useEffect(() => {
        // Safe to call even when disabled!
        posthog.capture("mycomponent_loaded", { foo: "bar" })
    }, [])
}
```
Tokens:
Raw