AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

omnibus-instrument-integration

Add PostHog SDK integration to your application. Use when setting up PostHog for the first time or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration for any framework.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--omnibus-instrument-integration at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 61

references/react-native.md

React Native - Docs

Installation

Our React Native enables you to integrate PostHog with your React Native project. For React Native projects built with Expo, there are no mobile native dependencies outside of supported Expo packages.

To install, add the posthog-react-native package to your project as well as the required peer dependencies.

Expo apps

Terminal

PostHog AI

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

React Native apps

Terminal

PostHog AI

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

React Native Web and macOS

If you're using React Native Web or React Native macOS, do not use the expo-file-system package since the Web and macOS targets aren't supported, use the @react-native-async-storage/async-storage package instead.

Configuration

With the PosthogProvider

The recommended way to set up PostHog for React Native is to use the PostHogProvider. This utilizes the Context API to pass the PostHog client around, and enables autocapture.

To set up PostHogProvider, add it to your App.js or App.ts file:

App.js

PostHog AI

// 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>
    )
}

Then you can access PostHog using the usePostHog() hook:

React Native

PostHog AI

const MyComponent = () => {
    const posthog = usePostHog()
    useEffect(() => {
        posthog.capture("event_name")
    }, [posthog])
}

Without the PosthogProvider

If you prefer not to use the provider, you can initialize PostHog in its own file and import the instance from there:

posthog.ts

PostHog AI

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'
})

Then you can access PostHog by importing your instance:

React Native

PostHog AI

import { posthog } from './posthog'
export function MyApp1() {
    useEffect(() => {
        posthog.capture('event_name')
    }, [])
    return <View>Your app code</View>
}

You can even use this instance with the PostHogProvider:

React Native

PostHog AI

import { posthog } from './posthog'
export function MyApp() {
  return <PostHogProvider client={posthog}>{/* Your app code */}</PostHogProvider>
}

Set up a reverse proxy (recommended)

We recommend setting up a reverse proxy, so that events are less likely to be intercepted by tracking blockers.

We have our own managed reverse proxy service, which is free for all PostHog Cloud users, routes through our infrastructure, and makes setting up your proxy easy.

If you don't want to use our managed service then there are several other options for creating a reverse proxy, including using Cloudflare, AWS Cloudfront, and Vercel.

Grouping products in one project (recommended)

If you have multiple customer-facing products (e.g. a marketing website + mobile app + web app), it's best to install PostHog on them all and group them in one project.

This makes it possible to track users across their entire journey (e.g. from visiting your marketing website to signing up for your product), or how they use your product across multiple platforms.

Add IPs to Firewall/WAF allowlists (recommended)

For certain features like heatmaps, your Web Application Firewall (WAF) may be blocking PostHog’s requests to your site. Add these IP addresses to your WAF allowlist or rules to let PostHog access your site.

EU: 3.75.65.221, 18.197.246.42, 3.120.223.253

US: 44.205.89.55, 52.4.194.122, 44.208.188.173

These are public, stable IPs used by PostHog services (e.g., Celery tasks for snapshots).

Configuration options

You can further customize how PostHog works through its configuration on initialization.

| Attribute | Description | | --- | --- | | hostType: StringDefault: https://us.i.posthog.com | PostHog API host (usually https://us.i.posthog.com by default or https://eu.i.posthog.com). Host is optional if you use https://us.i.posthog.com. | | flushAtType: NumberDefault: 20 | The number of events to queue before sending to PostHog (flushing). | | flushIntervalType: NumberDefault: 10000 | The interval in milliseconds between periodic flushes. | | maxBatchSizeType: NumberDefault: 100 | The maximum number of queued messages to be flushed as part of a single batch (must be higher than flushAt). | | maxQueueSizeType: NumberDefault: 1000 | The maximum number of cached messages either in memory or on the local storage (must be higher than flushAt). | | disabledType: BooleanDefault: false | If set to true, the SDK is essentially disabled (useful for local environments where you don't want to track anything). | | defaultOptInType: BooleanDefault: true | If set to false, the SDK will not track until the optIn() function is called. | | sendFeatureFlagEventType: BooleanDefault: true | Whether to track that getFeatureFlag was called (used by experiments). | | preloadFeatureFlagsType: BooleanDefault: true | Whether to load feature flags when initialized or not. | | bootstrapType: ObjectDefault: {} | An object containing the distinctId, isIdentifiedId, featureFlags, and featureFlagPayloads keys. distinctId is a string, and featureFlags and featureFlagPayloads are objects of key-value pairs. Used to ensure data is available as soon as the SDK loads. | | fetchRetryCountType: NumberDefault: 3 | How many times HTTP requests will be retried. | | fetchRetryDelayType: NumberDefault: 3000 | The delay between HTTP request retries. | | requestTimeoutType: NumberDefault: 10000 | Timeout in milliseconds for any calls. | | featureFlagsRequestTimeoutMsType: NumberDefault: 10000 | Timeout in milliseconds for feature flag calls. | | sessionExpirationTimeSecondsType: NumberDefault: 1800 | For session analysis, how long before a session expires (defaults to 30 minutes). | | persistenceType: StringDefault: file | Allows you to provide the storage type. file will try to load the best available storage, the provided customStorage, customAsyncStorage, or in-memory storage. | | customAppPropertiesType: Object or FunctionDefault: null | Allows you to provide your own implementation of the common information about your App or a function to modify the default App properties generated. | | customStorageType: ObjectDefault: null | 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. If persistence is set to memory, this option is ignored. | | captureAppLifecycleEventsType: BooleanDefault: false | Captures app lifecycle events such as Application Installed, Application Updated, Application Opened, Application Became Active, and Application Backgrounded. By default, this is false. | | disableGeoipType: BooleanDefault: false | When true, disables automatic GeoIP resolution for events and feature flags. | | enableSessionReplayType: BooleanDefault: false | Enable Recording of Session replay for Android and iOS. | | sessionReplayConfigType: ObjectDefault: null | Session replay configuration. See the replay install docs for more details. | | enablePersistSessionIdAcrossRestartType: BooleanDefault: false | When true, persists the $session_id across app restarts. If false, $session_id always resets on app restart. | | evaluationContextsType: Array of StringsDefault: undefined | Evaluation context tags that constrain which feature flags are evaluated. When set, only flags with matching evaluation context tags (or no evaluation context tags) will be returned. This helps reduce unnecessary flag evaluations and improves performance. See evaluation contexts documentation for more details. Available in version 4.8.0+. The legacy parameter evaluationEnvironments (version 4.7.2+) is also supported for backward compatibility. | | before_sendType: FunctionDefault: undefined | A callback function that is called before each event is sent to PostHog. You can use it to modify, filter, or suppress events. Return null to drop the event, or return the modified event to send it. See customizing exception capture for details. |

Capturing events

You can send custom events using capture:

React Native

PostHog AI

posthog.capture('user_signed_up')

Tip: We recommend using a [object] [verb] format for your event names, where [object] is the entity that the behavior relates to, and [verb] is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can include additional information with the event by including a properties object:

React Native

PostHog AI

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

Capturing screen views

With @react-navigation/native and autocapture:

When using @react-navigation/native v6 or lower, screen tracking is automatically captured if the autocapture property is used in the PostHogProvider:

It is important that the PostHogProvider is configured as a child of the NavigationContainer:

React Native

PostHog AI

// 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>
    )
}

When using @react-navigation/native v7 or higher, screen tracking has to be manually captured:

React Native

PostHog AI

// 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>
    )
}

Check out and set it up the official way for Screen tracking for analytics.

Then call the screen method within the trackScreenView method.

React Native

PostHog AI

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)

With react-native-navigation and autocapture:

First, simplify the wrapping of your screens with a shared PostHogProvider:

React Native

PostHog AI

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>
  );
};

Then, every screen needs to be wrapped with this provider if you want to capture touches or use the usePostHog() hook

React Native

PostHog AI

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,
  });
});

With expo-router:

Check out and set it up the official way for Screen tracking for analytics.

Then call the screen method within the useEffect callback.

React Native

PostHog AI

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

Manually capturing screen capture events

If you prefer not to use autocapture, you can manually capture screen views by calling posthog.screen(). This function requires a name. You may also pass in an optional properties object.

JavaScript

PostHog AI

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

Autocapture

PostHog autocapture can automatically track the following events for you:

  • Application Opened - when the app is opened from a closed state
  • Application Became Active - when the app comes to the foreground (e.g. from the app switcher)
  • Application Backgrounded - when the app is sent to the background by the user
  • Application Installed - when the app is installed.
  • Application Updated - when the app is updated.
  • $screen - when the user navigates (if using @react-navigation/native (v6 or lower) or react-native-navigation), check out the capturing screen views section
  • $autocapture - touch events when the user interacts with the screen
  • $exception - when the app throws exceptions.

⚠️ React Navigation v7 users

React Navigation v7 restricts navigation hooks (such as useNavigationState) to components rendered inside a Screen that belongs to a Navigator.

Because of this change, automatic screen tracking may throw errors if PostHog is initialized outside a screen context. This commonly affects apps upgrading from React Navigation v6 to v7.

For React Navigation v7, we recommend disabling automatic screen capture for screens and manually calling posthog.screen() inside each screen component. See the Capturing screen views section below.

With autocapture, all touch events for children of PosthogProvider are tracked, capturing a snapshot of the view hierarchy at that point. This enables you to create insights in PostHog without having to add custom events.

PostHog will try to generate a sensible name for the touched element based on the React component displayName or name. If you prefer, you can set your own name using the ph-label prop:

React Native

PostHog AI

<View ph-label="my-special-label"></View>

Autocapture configuration

React Native

PostHog AI

<PostHogProvider apiKey="<ph_project_token>" autocapture={{
    captureTouches: true,
    captureScreens: true,
    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>

Preventing sensitive data capture

If there are elements you don't want to be captured, you can add the ph-no-capture property. If this property is found anywhere in the view hierarchy, the entire touch event is ignored:

React Native

PostHog AI

<View ph-no-capture>Sensitive view here</View>

Identifying users

We highly recommend reading our section on Identifying users to better understand how to correctly use this method.

Using identify, you can associate events with specific users. This enables you to gain full insights as to how they're using your product across different sessions, devices, and platforms.

An identify call has the following arguments:

  • distinctId: Required. A unique identifier for your user. Typically either their email or database ID.
  • properties: Optional. A dictionary with key:value pairs to set the person properties

React Native

PostHog AI

posthog.identify('distinctID',
  { // ($set):
      email: '[email protected]',
      name: 'My Name'
  }
)

$set_once works just like $set, except that it will only set the property if the user doesn't already have that property set. See the difference between $set and $set_once

React Native

PostHog AI

posthog.identify('distinctID',
  {
    $set: {
        email: '[email protected]',
        name: 'My Name'
    },
    $set_once: {
        date_of_first_log_in: '2024-03-01'
    }
  }
)

You should call identify as soon as you're able to. Typically, this is after your user logs in. This ensures that events sent during your user's sessions are correctly associated with them.

When you call identify, all previously tracked anonymous events will be linked to the user.

Get 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.

To do this, call posthog.get_distinct_id(). This returns either the ID automatically generated by PostHog or the ID that has been passed by a call to identify().

Alias

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.

In this case, you can use alias to assign another distinct ID to the same user.

React Native

PostHog AI

// Sets alias for current user
posthog.alias('distinct_id')

We strongly recommend reading our docs on alias to best understand how to correctly use this method.

Setting person properties

Person properties enable you to capture, manage, and analyze specific data about a user. You can use them to create filters or cohorts, which can then be used in insights, feature flags, and more.

To set a user's properties, include the $set or $set_once property when capturing any event:

$set

JavaScript

PostHog AI

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

$set_once

$set_once works just like $set, except it only sets the property if the user doesn't already have that property set.

JavaScript

PostHog AI

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

Super properties

Super properties are properties associated with events that are set once and then sent with every capture call, be it a $screen, an autocaptured touch, or anything else.

They are set using posthog.register, which takes a properties object as a parameter, and they persist across sessions.

For example:

JavaScript

PostHog AI

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

The call above ensures that every event sent by the user will include "icecream pref": "vanilla" and "team_id": 22. This way, if you filtered events by property using icecream_pref = vanilla, it would display all events captured on that user after the posthog.register call, since they all include the specified Super Property.

This does not set the user's properties. This only sets the properties for their events. To store person properties, see the setting person properties section.

Removing stored super properties

Super Properties are persisted across sessions so you have to explicitly remove them if they are no longer relevant. In order to stop sending a Super Property with events, you can use posthog.unregister, like so:

JavaScript

PostHog AI

posthog.unregister('icecream pref'),

This will remove the super property and subsequent events will not include it.

If you are doing this as part of a user logging out you can instead simply posthog.reset() which takes care of clearing all stored Super Properties and more.

Opt out of data capture

You can completely opt-out users from data capture. To do this, there are two options:

  1. Opt users out by default by setting opt_out_capturing_by_default to true in your PostHog config:

JavaScript

PostHog AI

posthog.init('<ph_project_token>', {
    opt_out_capturing_by_default: true,
});
  1. Opt users out on a per-person basis by calling opt_out_capturing():

JavaScript

PostHog AI

posthog.opt_out_capturing()

Similarly, you can opt users in:

JavaScript

PostHog AI

posthog.opt_in_capturing()

To check if a user is opted out:

JavaScript

PostHog AI

posthog.has_opted_out_capturing()

Flush

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 configure the flush interval. By default we flush all events after 30 seconds, no matter how many events have gathered.

You can also manually flush the queue. If a flush is alr