Installation

Our React Native SDK enables you to integrate Leanbase 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 leanbase-react-native package to your project as well as the required peer dependencies.

Expo apps

React Native apps

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 LeanbaseProvider

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

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

Then you can access Leanbase using the useLeanBase() hook:

Without the LeanbaseProvider

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

Then you can access Leanbase by importing your instance:

You can even use this instance with the LeanBaseProvider:

Configuration options

Capturing events

You can send custom events using capture:

Setting event properties

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

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 LeanBaseProvider:

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

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

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

Then call the screen method within the trackScreenView method.

With react-native-navigation and autocapture:

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

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

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.

Manually capturing screen capture events

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

Identifying users

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.

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

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 leanbase.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.In this case, you can use alias to assign another distinct ID to the same user.

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

$set_once

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

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 leanbase.register, which takes a properties object as a parameter, and they persist across sessions.

For example:

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.

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 leanbase.unregister, like so:

Autocapture

Leanbase 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

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

Leanbase 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:

Autocapture configuration

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:

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 Leanbase config:

2. Opt users out on a per-person basis by calling opt_out_capturing():

Similarly, you can opt users in:

To check if a user is opted out:

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 already in progress it returns a promise for the existing flush.

Reset after logout

To reset the user's ID and anonymous ID, call reset. Usually you would do this right after the user logs out.

Offline behavior

The Leanbase React Native SDK will continue to capture events when the device is offline. When persistence is set to file (by default), the events are stored in a queue in the device's file storage. Even when the app is closed, the events are persisted and will be flushed when the app is opened again.

• The queue has a maximum size defined by maxQueueSize in the configuration.

• When the queue is full, the oldest event is deleted first.

• The queue is flushed only when the device is online.

Opt-in / Opt-out

By default, LeanBase has tracking enabled unless it is forcefully disabled by default using the option { defaultOptIn: false }.

You can give your users the option to opt in or out by calling the relevant methods. Once these have been called they are persisted and will be respected until optIn/Out is called again or the reset function is called.

To opt in/out of tracking, use the following calls.

If you still wish capture these events but want to create a distinction between users and team in Leanbase, you should look into Cohorts.

Group analytics

1. Associate events with a team or organization:

2. Associate the events for this session with a group AND update the properties of that group

The name is a special property which is used in the PostHog UI for the name of the group. If you don't specify a name property, the group ID will be used instead.

Disabling for local development

You may want to disable Leanbase when working locally or in a test environment. You can do this by setting the disable option to true when initializing Leanbase. Helpfully this allows you to continue using useLeanBase and safely calling it without anything actually happening.