PostHog React Native SDK
SDK Version: 4.5.1
PostHog
Initialization methods
PostHogProvider
public
PostHogProvider is a React component that provides PostHog functionality to your React Native app. You can find all configuration options in the React Native SDK docs.
Autocapturing navigation requires further configuration. See the React Native SDK navigation docs for more information about autocapturing navigation.
This is the recommended way to set up PostHog for React Native. This utilizes the Context API to pass the PostHog client around, enable autocapture.
Parameters
Name | Type |
---|---|
{ children, client, options, apiKey, autocapture, style, debug, } | PostHogProviderProps |
Examples
Returns
Type | |
---|---|
Union of | JSX.Element |
null |
PostHog
public
Creates a new PostHog instance for React Native. You can find all configuration options in the React Native SDK docs.
If you prefer not to use the PostHogProvider, you can initialize PostHog in its own file and import the instance from there.
Parameters
Name | Type |
---|---|
apiKey | string |
Your PostHog API key | |
options? | PostHogOptions |
PostHog configuration options |
Examples
Returns
Type |
---|
any |
debug
public
Enables or disables debug mode for detailed logging.
Notes:
Debug mode logs all PostHog calls to the console for troubleshooting. This is useful during development to understand what data is being sent.
Parameters
Name | Type |
---|---|
enabled? | boolean |
Examples
Returns
Type |
---|
void |
shutdown
public
Shuts down the PostHog instance and ensures all events are sent.
Call shutdown() once before the process exits to ensure that all events have been sent and all promises have resolved. Do not use this function if you intend to keep using this PostHog instance after calling it. Use flush() for per-request cleanup instead.
Parameters
Name | Type |
---|---|
shutdownTimeoutMs? | number |
Maximum time to wait for shutdown in milliseconds |
Examples
Returns
Type |
---|
Promise<void> |
Capture methods
flush
public
Manually flushes the event queue.
You can set the number of events in the configuration that should queue before flushing. Setting this to 1 will send events immediately and will use more battery. This is set to 20 by default. You can also manually flush the queue. If a flush is already in progress it returns a promise for the existing flush.
Examples
Returns
Type |
---|
Promise<void> |
register
public
Registers super properties that are sent with every event.
Super properties are properties associated with events that are set once and then sent with every capture call. They persist across sessions and are stored locally.
Parameters
Name | Type |
---|---|
properties | PostHogEventProperties |
An associative array of properties to store about the user |
Examples
Returns
Type |
---|
Promise<void> |
screen
public
Captures a screen view event.
Notes:
This function requires a name. You may also pass in an optional properties object. Screen name is automatically registered for the session and will be included in subsequent events.
Parameters
Name | Type |
---|---|
name | string |
The name of the screen | |
properties? | PostHogEventProperties |
Optional properties to include with the screen event | |
options? | PostHogCaptureOptions |
Optional capture options |
Examples
Returns
Type |
---|
Promise<void> |
unregister
public
Removes a super property so it won't be sent with future events.
Super Properties are persisted across sessions so you have to explicitly remove them if they are no longer relevant.
Parameters
Name | Type |
---|---|
property | string |
The name of the super property to remove |
Examples
Returns
Type |
---|
Promise<void> |
Error tracking methods
captureException
public
Capture a caught exception manually
Parameters
Name | Type |
---|---|
error | unknown |
The error to capture | |
additionalProperties? | PostHogEventProperties |
Any additional properties to add to the error event |
Examples
Returns
Type |
---|
void |
Feature flags methods
getFeatureFlag
public
Gets the value of a feature flag for the current user.
Defaults to undefined if not loaded yet or if there was a problem loading. Multivariant feature flags are returned as a string.
Parameters
Name | Type |
---|---|
key | string |
The feature flag key |
Examples
Returns
Type | |
---|---|
Union of | boolean |
string | |
undefined |
getFeatureFlagPayload
public
Gets the payload of a feature flag for the current user.
Returns JsonType or undefined if not loaded yet or if there was a problem loading.
Parameters
Name | Type |
---|---|
key | string |
The feature flag key |
Examples
Returns
Type | |
---|---|
Union of | JsonType |
undefined |
isFeatureEnabled
public
Checks if a feature flag is enabled for the current user.
Defaults to undefined if not loaded yet or if there was a problem loading.
Parameters
Name | Type |
---|---|
key | string |
The feature flag key |
Examples
Returns
Type | |
---|---|
Union of | boolean |
undefined |
reloadFeatureFlags
public
Reloads feature flags from the server.
PostHog loads feature flags when instantiated and refreshes whenever methods are called that affect the flag. If you want to manually trigger a refresh, you can call this method.
Examples
Returns
Type |
---|
void |
reloadFeatureFlagsAsync
public
Reloads feature flags from the server asynchronously.
PostHog loads feature flags when instantiated and refreshes whenever methods are called that affect the flag. If you want to manually trigger a refresh and get the result, you can call this method.
Examples
Returns
Type | |
---|---|
Union of | Promise<Record<string, boolean |
string> | |
undefined> |
resetGroupPropertiesForFlags
public
Resets group properties for feature flag evaluation.
Examples
Returns
Type |
---|
void |
resetPersonPropertiesForFlags
public
Resets person properties for feature flag evaluation.
Examples
Returns
Type |
---|
void |
setGroupPropertiesForFlags
public
Sets group properties for feature flag evaluation.
These properties are automatically attached to the current group (set via posthog.group()). When you change the group, these properties are reset.
Parameters
Name | Type |
---|---|
properties | Record<string, Record<string, string>> |
The group properties to set for flag evaluation |
Examples
Returns
Type |
---|
void |
setPersonPropertiesForFlags
public
Sets person properties for feature flag evaluation.
Sometimes, you might want to evaluate feature flags using properties that haven't been ingested yet, or were set incorrectly earlier. You can do so by setting properties the flag depends on with this call. These are set for the entire session. Successive calls are additive: all properties you set are combined together and sent for flag evaluation.
Parameters
Name | Type |
---|---|
properties | Record<string, string> |
The person properties to set for flag evaluation |
Examples
Returns
Type |
---|
void |
Group analytics methods
group
public
Associates the current user with a group.
Group analytics allows you to associate the events for that person's session with a group (e.g. teams, organizations, etc.). This is a paid feature and is not available on the open-source or free cloud plan.
Parameters
Name | Type |
---|---|
groupType | string |
The type of group (e.g. 'company', 'team') | |
groupKey | string |
The unique identifier for the group | |
properties? | PostHogEventProperties |
Optional properties to set for the group |
Examples
Returns
Type |
---|
void |
Identification methods
alias
public
Assigns an alias to the current user.
Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.
Parameters
Name | Type |
---|---|
alias | string |
The alias to assign to the current user |
Examples
Returns
Type |
---|
void |
getDistinctId
public
Gets the current user's distinct ID.
You may find it helpful to get the current user's distinct ID. For example, to check whether you've already called identify for a user or not. This returns either the ID automatically generated by PostHog or the ID that has been passed by a call to identify().
Examples
Returns
Type |
---|
string |
identify
public
Associates events with a specific user. Learn more about identifying users
Parameters
Name | Type |
---|---|
distinctId? | string |
A unique identifier for your user. Typically either their email or database ID. | |
properties? | PostHogEventProperties |
Optional dictionary with key:value pairs to set the person properties | |
options? | PostHogCaptureOptions |
Optional capture options |
Examples
Returns
Type |
---|
void |
reset
public
Resets the user's ID and anonymous ID after logout.
To reset the user's ID and anonymous ID, call reset. Usually you would do this right after the user logs out. This also clears all stored super properties and more.
Examples
Returns
Type |
---|
void |
getAnonymousId
public
Returns the current anonymous ID.
This is the ID assigned to users before they are identified. It's used to track anonymous users and link them to identified users when they sign up.
Examples
Returns
Type |
---|
string |
LLM analytics methods
captureTraceFeedback
public
Capture written user feedback for a LLM trace. Numeric values are converted to strings.
Parameters
Name | Type |
---|---|
traceId | string | number |
The trace ID to capture feedback for. | |
userFeedback | string |
The feedback to capture. |
Examples
Returns
Type |
---|
void |
captureTraceMetric
public
Capture a metric for a LLM trace. Numeric values are converted to strings.
Parameters
Name | Type |
---|---|
traceId | string | number |
The trace ID to capture the metric for. | |
metricName | string |
The name of the metric to capture. | |
metricValue | string | number | boolean |
The value of the metric to capture. |
Examples
Returns
Type |
---|
void |
Privacy methods
optIn
public
Opts the user in to data capture.
By default, PostHog has tracking enabled unless it is forcefully disabled by default using the option defaultOptIn: false . Once this has been called it is persisted and will be respected until optOut is called again or the reset function is called.
Examples
Returns
Type |
---|
Promise<void> |
optOut
public
Opts the user out of data capture.
You can completely opt-out users from data capture. Once this has been called it is persisted and will be respected until optIn is called again or the reset function is called.
Examples
Returns
Type |
---|
Promise<void> |
Other methods
fetch
public
Parameters
Name | Type |
---|---|
url | string |
options | PostHogFetchOptions |
Examples
Returns
Type |
---|
Promise<PostHogFetchResponse> |
getCommonEventProperties
public
Examples
Returns
getCustomUserAgent
public
Examples
Returns
Type |
---|
string |
getLibraryId
public
Examples
Returns
Type |
---|
string |
getLibraryVersion
public
Examples
Returns
Type |
---|
string |
getPersistedProperty
public
Parameters
Name | Type |
---|---|
key | PostHogPersistedProperty |
Examples
Returns
Type | |
---|---|
Union of | T |
undefined |
getSessionId
public
Examples
Returns
Type |
---|
string |
getSurveys
public
Examples
Returns
Type |
---|
Promise<SurveyResponse['surveys']> |
initReactNativeNavigation
public
Parameters
Name | Type |
---|---|
options | PostHogAutocaptureOptions |
Examples
Returns
Type |
---|
boolean |
resetSessionId
public
Examples
Returns
Type |
---|
void |
setPersistedProperty
public
Parameters
Name | Type |
---|---|
key | PostHogPersistedProperty |
value | T | null |
Examples
Returns
Type |
---|
void |
autocapture
public
Parameters
Name | Type |
---|---|
eventType | string |
elements | PostHogAutocaptureElement[] |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
void |
capture
public
Parameters
Name | Type |
---|---|
event | string |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
void |
getFeatureFlagDetails
public
Examples
Returns
Type | |
---|---|
Union of | PostHogFeatureFlagDetails |
undefined |
getFeatureFlagPayloads
public
Examples
Returns
Type | |
---|---|
Union of | PostHogFlagsResponse['featureFlagPayloads'] |
undefined |
getFeatureFlags
public
Examples
Returns
Type | |
---|---|
Union of | PostHogFlagsResponse['featureFlags'] |
undefined |
getFeatureFlagsAndPayloads
public
Examples
Returns
Type | |
---|---|
Union of | {
flags: PostHogFlagsResponse['featureFlags'] |
undefined;
payloads: PostHogFlagsResponse['featureFlagPayloads'] | |
undefined;
} |
getKnownFeatureFlags
public
Examples
Returns
Type | |
---|---|
Union of | PostHogFlagsResponse['featureFlags'] |
undefined |
groupIdentify
public
Parameters
Name | Type |
---|---|
groupType | string |
groupKey | string | number |
groupProperties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
void |
Examples
Returns
Type |
---|
void |
on
public
Parameters
Name | Type |
---|---|
event | string |
cb | (...args: any[]) => void |
Examples
Returns
Type |
---|
() => void |
onFeatureFlag
public
Parameters
Name | Type |
---|---|
key | string |
cb | (value: FeatureFlagValue) => void |
Examples
Returns
Type |
---|
() => void |
onFeatureFlags
public
Parameters
Name | Type |
---|---|
cb | (flags: PostHogFlagsResponse['featureFlags']) => void |
Examples
Returns
Type |
---|
() => void |
overrideFeatureFlag
public
Parameters
Name | Type |
---|---|
flags | PostHogFlagsResponse['featureFlags'] | null |
Examples
Returns
Type |
---|
Promise<void> |
registerForSession
public
Parameters
Name | Type |
---|---|
properties | PostHogEventProperties |
Examples
Returns
Type |
---|
void |
reloadRemoteConfigAsync
public
Examples
Returns
Type | |
---|---|
Union of | Promise<PostHogRemoteConfig |
undefined> |
setupBootstrap
public
Parameters
Name | Type |
---|---|
options? | Partial<PostHogCoreOptions> |
Examples
Returns
Type |
---|
void |
unregisterForSession
public
Parameters
Name | Type |
---|---|
property | string |
Examples
Returns
Type |
---|
void |
addPendingPromise
public
Parameters
Name | Type |
---|---|
promise | Promise<T> |
Examples
Returns
Type |
---|
Promise<T> |
aliasStateless
public
Parameters
Name | Type |
---|---|
alias | string |
distinctId | string |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
void |
aliasStatelessImmediate
public
Parameters
Name | Type |
---|---|
alias | string |
distinctId | string |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
Promise<void> |
captureStateless
public
Parameters
Name | Type |
---|---|
distinctId | string |
event | string |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
void |
captureStatelessImmediate
public
Parameters
Name | Type |
---|---|
distinctId | string |
event | string |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
Promise<void> |
enqueue
public
- ** QUEUEING AND FLUSHING *
Parameters
Name | Type |
---|---|
type | string |
_message | any |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
void |
getCustomHeaders
public
Examples
Returns
Type |
---|
{
[key: string]: string;
} |
getFeatureFlagDetailsStateless
public
Parameters
Name | Type |
---|---|
distinctId | string |
groups? | Record<string, string | number> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
disableGeoip? | boolean |
flagKeysToEvaluate? | string[] |
Examples
Returns
Type | |
---|---|
Union of | Promise<PostHogFeatureFlagDetails |
undefined> |
getFeatureFlagDetailStateless
public
Parameters
Name | Type |
---|---|
key | string |
distinctId | string |
groups? | Record<string, string> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
disableGeoip? | boolean |
Examples
Returns
Type | |
---|---|
Union of | Promise<{
response: FeatureFlagDetail |
undefined;
requestId: string | |
undefined;
} | |
undefined> |
getFeatureFlagPayloadsStateless
public
Parameters
Name | Type |
---|---|
distinctId | string |
groups? | Record<string, string> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
disableGeoip? | boolean |
flagKeysToEvaluate? | string[] |
Examples
Returns
Type | |
---|---|
Union of | Promise<PostHogFlagsResponse['featureFlagPayloads'] |
undefined> |
getFeatureFlagPayloadStateless
public
Parameters
Name | Type |
---|---|
key | string |
distinctId | string |
groups? | Record<string, string> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
disableGeoip? | boolean |
Examples
Returns
Type | |
---|---|
Union of | Promise<JsonType |
undefined> |
getFeatureFlagsAndPayloadsStateless
public
Parameters
Name | Type |
---|---|
distinctId | string |
groups? | Record<string, string | number> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
disableGeoip? | boolean |
flagKeysToEvaluate? | string[] |
Examples
Returns
Type | |
---|---|
Union of | Promise<{
flags: PostHogFlagsResponse['featureFlags'] |
undefined;
payloads: PostHogFlagsResponse['featureFlagPayloads'] | |
undefined;
requestId: PostHogFlagsResponse['requestId'] | |
undefined;
}> |
getFeatureFlagsStateless
public
Parameters
Name | Type |
---|---|
distinctId | string |
groups? | Record<string, string | number> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
disableGeoip? | boolean |
flagKeysToEvaluate? | string[] |
Examples
Returns
Type | |
---|---|
Union of | Promise<{
flags: PostHogFlagsResponse['featureFlags'] |
undefined;
payloads: PostHogFlagsResponse['featureFlagPayloads'] | |
undefined;
requestId: PostHogFlagsResponse['requestId'] | |
undefined;
}> |
getFeatureFlagStateless
public
Parameters
Name | Type |
---|---|
key | string |
distinctId | string |
groups? | Record<string, string> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
disableGeoip? | boolean |
Examples
Returns
Type | |
---|---|
Union of | Promise<{
response: FeatureFlagValue |
undefined;
requestId: string | |
undefined;
}> |
getFlags
public
- ** FEATURE FLAGS *
Parameters
Name | Type |
---|---|
distinctId | string |
groups? | Record<string, string | number> |
personProperties? | Record<string, string> |
groupProperties? | Record<string, Record<string, string>> |
extraPayload? | Record<string, any> |
Examples
Returns
Type | |
---|---|
Union of | Promise<PostHogFlagsResponse |
undefined> |
getRemoteConfig
public
Examples
Returns
Type | |
---|---|
Union of | Promise<PostHogRemoteConfig |
undefined> |
getSurveysStateless
public
- ** SURVEYS *
Examples
Returns
Type |
---|
Promise<SurveyResponse['surveys']> |
groupIdentifyStateless
public
- ** GROUPS *
Parameters
Name | Type |
---|---|
groupType | string |
groupKey | string | number |
groupProperties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
distinctId? | string |
eventProperties? | PostHogEventProperties |
Examples
Returns
Type |
---|
void |
identifyStateless
public
- ** TRACKING *
Parameters
Name | Type |
---|---|
distinctId | string |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
void |
identifyStatelessImmediate
public
Parameters
Name | Type |
---|---|
distinctId | string |
properties? | PostHogEventProperties |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
Promise<void> |
logMsgIfDebug
public
Parameters
Name | Type |
---|---|
fn | () => void |
Examples
Returns
Type |
---|
void |
sendImmediate
public
Parameters
Name | Type |
---|---|
type | string |
_message | any |
options? | PostHogCaptureOptions |
Examples
Returns
Type |
---|
Promise<void> |
wrap
public
Parameters
Name | Type |
---|---|
fn | () => void |
Examples
Returns
Type |
---|
void |