PostHogOptions

Captures app lifecycle events such as Application Installed, Application Updated, Application Opened, Application Became Active and Application Backgrounded. Application Installed and Application Updated events are not supported with persistence set to 'memory'. true

Whether to automatically capture $push_notification_opened on a notification tap. Requires @posthog/react-native-plugin. Fires for pushes from any provider, not just PostHog's — but title and body are attached only for PostHog's own, so third-party notification text never reaches analytics. Android sees cold starts only; call for the taps it misses. The native SDK builds and sends this event, so JS before_send never sees it. Not supported on web. true

Whether to automatically register this device's push token so PostHog Workflows can target it. Requires @posthog/react-native-plugin. Your app still owns permission — PostHog only observes the token the OS hands back, and never sees later refreshes. Forward those to yourself. Not supported on web or macOS. true

Allows you to provide your own implementation of the common information about your App or a function to modify the default App properties generated

Allows you to provide a custom asynchronous storage such as async-storage, expo-file-system or a synchronous storage such as mmkv. If not provided, PostHog will attempt to use the best available storage via optional peer dependencies (async-storage, expo-file-system). If persistence is set to 'memory', this option will be ignored.

If enabled, the session id ($session_id) will be persisted across app restarts. This is an option for back compatibility, so your current data isn't skewed with the new version of the SDK. If this is false, the session id will be always reset on app restart. false

Enable Recording of Session Replays for Android and iOS Requires Record user sessions to be enabled in the PostHog Project Settings false

Error Tracking Configuration

Logs feature configuration. Enables structured log capture via posthog.captureLog(...) or posthog.logger.info(...). Records ship to PostHog's logs product (/i/v1/logs) in OTLP format, batched on a timer, AppState change, buffer fill, or manual flushLogs(). Capture is unconditional — calling the API ships records as long as the SDK is initialized and the user hasn't opted out. The only blockers are optedOut, missing/empty body, and missing API key. All fields below are optional; per-SDK defaults apply (mobile defaults are tuned for cellular bandwidth and battery, ~50 logs/sec ceiling).

Overrides the language used when rendering translated survey copy. When unset, the SDK falls back to the persisted person property language and then the device locale.

Allows you to provide the storage type. 'file' will try to load the best available storage, the provided 'customStorage', 'customAsyncStorage' or in-memory storage. 'file'

Mints a signed identity-verification token for push subscription requests. Only needed when your PostHog project requires identity verification for push. Requires @posthog/react-native-plugin. Called with the current distinctId and appId. Mint on your backend (HS256, sub = distinctId, an app_id claim, aud = posthog:push_identity), never in the app. Return null to send the request unauthenticated; a slow or throwing implementation does the same after 10 seconds.

A list of headers that should be sent with requests to the PostHog API.

Configuration for Session Replay

Automatically include common device and app properties in feature flag evaluation. When enabled, the following properties are sent with every /flags request: - $app_version: App version - $app_build: App build number - $app_namespace: App bundle identifier / namespace - $os_name: Operating system name - $os_version: Operating system version - $device_type: Device type (Mobile, Desktop) - $lib: Name of the SDK library - $lib_version: Version of the SDK library This ensures feature flags that rely on these properties work correctly without waiting for server-side processing of identify() calls. true