PostHogCoreOptions

Properties

Name	Type
`host`	`string`
PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
`flushAt`	`number`
The number of events to queue before sending to PostHog (flushing)
`flushInterval`	`number`
The interval in milliseconds between periodic flushes
`maxBatchSize`	`number`
The maximum number of queued messages to be flushed as part of a single batch (must be higher than `flushAt`)
`maxQueueSize`	`number`
The maximum number of cached messages either in memory or on the local storage (must be higher than `flushAt`)
`disabled`	`boolean`
If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything)
`defaultOptIn`	`boolean`
If set to false the SDK will not track until the `optIn` function is called.
`disable_capture_url_hashes`	`boolean`
Whether to strip URL fragments (`#...`) from automatically captured URL fields. Disabled by default for backwards compatibility. Set to `true` to strip hashes from: `$current_url` on automatically captured browser events, including `$pageview` `$initial_current_url` `$session_entry_url` `$elements[*].attr__href` and `$external_click_url` for autocapture and dead-click autocapture Next.js Pages Router `$pageview` `$current_url` web vitals `$current_url` logs `url.full` conversations `current_url` and `request_url` session replay rrweb meta/custom-event `href` URLs heatmap data URLs If your SPA relies on hash-based routes for analytics, enabling this is a breaking behavior change. If you want to capture hashes selectively, leave this as `false` and use `before_send` to remove sensitive hash values before events are sent.
`sendFeatureFlagEvent`	`boolean`
Whether to track that `getFeatureFlag` was called (used by Experiments)
`preloadFeatureFlags`	`boolean`
Whether to load feature flags when initialized or not
`disableRemoteFeatureFlags`	`boolean`
Advanced: whether to disable fetching and evaluating feature flags from PostHog entirely. When set to true, `reloadFeatureFlags()` and the reloads triggered by `identify()`, `group()`, `setPersonPropertiesForFlags()` and `reset()` become no-ops, and any request to the flags endpoint that still goes out (e.g. to fetch remote config or surveys) carries `disable_flags: true` so the server skips flag evaluation. Flag values must be supplied via the `bootstrap` option or `updateFlags()` instead; `getFeatureFlag()` and related methods keep working against those values. Until `updateFlags()` runs, reads return their not-loaded defaults, so use `bootstrap` for any flags needed at startup. Equivalent to the web SDK's `advanced_disable_feature_flags`. Note: surveys gated on feature flags will not evaluate unless the survey targeting flags are also provided via `updateFlags()`. This option cannot be toggled at runtime. `posthog-node` inherits this option but does not implement it (no-op).
`disableRemoteConfig`	`boolean`
Whether to load remote config when initialized or not Deprecated: Remote config is now always loaded and this option is a no-op. It will be removed in a future version.
`disableSurveys`	`boolean`
Whether to load surveys when initialized or not Requires the `PostHogSurveyProvider` to be used
`bootstrap`	`{ distinctId?: string; isIdentifiedId?: boolean; featureFlags?: Record<string, FeatureFlagValue>; featureFlagPayloads?: Record<string, JsonType>; }`
Option to bootstrap the library with given distinctId and feature flags
`fetchRetryCount`	`number`
How many times we will retry HTTP requests
`fetchRetryDelay`	`number`
The delay between HTTP request retries in milliseconds
`requestTimeout`	`number`
Timeout in milliseconds for any calls
`featureFlagsRequestTimeoutMs`	`number`
Timeout in milliseconds for feature flag calls
`featureFlagsRequestMaxRetries`	`number`
How many times feature flag requests retry after a transient network error. Set to 0 to disable feature flag request retries.
`remoteConfigRequestTimeoutMs`	`number`
Timeout in milliseconds for remote config calls
`sessionExpirationTimeSeconds`	`number`
For Session Analysis how long before we expire a session in seconds
`disableCompression`	`boolean`
Whether to disable GZIP compression
`disableGeoip`	`boolean`
Whether to disable GeoIP lookups
`historicalMigration`	`boolean`
Special flag to indicate ingested data is for a historical migration
`evaluationContexts`	`readonly string[]`
Evaluation contexts for feature flags. When set, only feature flags that have at least one matching evaluation tag will be evaluated for this SDK instance. Feature flags with no evaluation tags will always be evaluated. Examples: ['production', 'web', 'mobile']
`evaluationEnvironments`	`readonly string[]`
Evaluation environments for feature flags. Deprecated: Use evaluationContexts instead. This property will be removed in a future version.
`personProfiles`	`"always" \| "identified_only" \| "never"`
Determines when to create Person Profiles for users. 'always': Always create a person profile for every user (anonymous and identified). 'identified_only': Only create a person profile when the user is identified via identify(), alias(), or group(). Events captured before identification will NOT have person profiles and will be anonymous events. 'never': Never create person profiles. identify(), alias(), and group() will be no-ops.
`before_send`	`BeforeSendFn \| BeforeSendFn[]`
Allows modification or dropping of events before they're sent to PostHog. If an array is provided, the functions are run in order. If a function returns null, the event will be dropped.
`addTracingHeaders`	`string[]`
A list of hostnames for which to inject PostHog tracing headers (X-POSTHOG-DISTINCT-ID, X-POSTHOG-SESSION-ID) on outgoing `fetch` requests. Use this to link requests made from your app to session replays and LLM traces in PostHog. When set, the global `fetch` is patched on initialization and the headers are added to requests whose hostname matches one of the entries. Requires the SDK to wire up `patchFetchForTracingHeaders` against this option (currently supported in posthog-react-native).