Mixpanel React Native SDK

3.3.0 · active · verified Sun Apr 19

Mixpanel React Native SDK is the official open-source library for integrating Mixpanel analytics into React Native applications, supporting both iOS and Android platforms. It acts as a wrapper around Mixpanel's native SDKs and enables robust offline tracking capabilities. The current stable version is 3.3.0, with frequent minor and patch releases to include enhancements, security updates, and bug fixes, indicating an active development cadence. A key differentiator is its direct wrapping of native SDKs, ensuring consistency with native Mixpanel features, and its explicit support for data persistence via `async-storage` to handle offline scenarios reliably. It's designed for React Native v0.6+ and ships with TypeScript types.

Common errors

```
TypeError: Cannot read property 'getItem' of undefined
```
cause The `@react-native-async-storage/async-storage` dependency is missing or not correctly linked, which is required for data persistence.

fix Install `@react-native-async-storage/async-storage` and run `pod install` for iOS: `npm install @react-native-async-storage/async-storage && cd ios && pod install`
```
Invariant Violation: 'main' has not been registered. This can happen if:
```
cause Common React Native setup issue, often related to the Metro bundler or app registration.

fix Ensure your `index.js` or `index.ts` file correctly registers the root component. Also, try clearing the Metro bundler cache (`npm start --reset-cache`) and reinstalling node modules (`rm -rf node_modules && npm install`).
```
Error: Mixpanel has not been initialized. Call init() before tracking.
```
cause Attempting to use Mixpanel tracking methods (`track`, `identify`, etc.) before calling `mixpanel.init()`.

fix Ensure `mixpanel.init()` is called once, typically in a `useEffect` hook for functional components or `componentDidMount` for class components, before any tracking methods are invoked.

Warnings

breaking As of v3.2.0, `@react-native-async-storage/async-storage` became a peer dependency. Your project must now explicitly install and manage this dependency. This change was implemented to avoid conflicts with frameworks like Expo.
Fix: Ensure `@react-native-async-storage/async-storage` is installed in your project: `npm install @react-native-async-storage/async-storage`.
gotcha Versions prior to v3.0.9 had a bug where the distinct ID could sometimes be `<nil>`, leading to inconsistent tracking data.
Fix: Upgrade to v3.0.9 or a newer version to resolve the distinct ID bug. `npm install mixpanel-react-native@latest`
gotcha When using Xcode versions between 12.5 and 13.2.1, a known Swift compile issue could occur.
Fix: Upgrade Xcode to version 13.2.1 or newer. If an upgrade is not possible, refer to the workaround mentioned in GitHub issue #43.

Install

npm install mixpanel-react-native npm
yarn add mixpanel-react-native yarn
pnpm add mixpanel-react-native pnpm

Imports

Mixpanel
wrong:
```
const Mixpanel = require('mixpanel-react-native').Mixpanel;
```
correct:
```
import { Mixpanel } from 'mixpanel-react-native';
```
The primary class for instantiating the Mixpanel client. The library is primarily consumed via ES Modules.
MixpanelInstance
```
import type { MixpanelInstance } from 'mixpanel-react-native';
```
Type import for the Mixpanel client instance, useful for TypeScript projects.
MixpanelProperties
```
import type { MixpanelProperties } from 'mixpanel-react-native';
```
Type import for event properties, allowing strong typing of tracking data in TypeScript.

Quickstart

This example demonstrates basic Mixpanel integration in a React Native app, including initialization, tracking custom events with properties, identifying a user, setting user profile properties, and resetting the Mixpanel instance.

import React, { useEffect } from 'react';
import { Button, SafeAreaView, Text, View } from 'react-native';
import { Mixpanel } from 'mixpanel-react-native';

const projectToken = process.env.MIXPANEL_PROJECT_TOKEN ?? 'YOUR_MIXPANEL_PROJECT_TOKEN'; // Replace with your Mixpanel project token
const trackAutomaticEvents = false;

const mixpanel = new Mixpanel(projectToken, trackAutomaticEvents);

export default function App() {
  useEffect(() => {
    mixpanel.init();
  }, []);

  const trackEvent = (eventName) => {
    mixpanel.track(eventName, { source: 'React Native App', time: new Date().toISOString() });
    console.log(`Tracked event: ${eventName}`);
  };

  const identifyUser = () => {
    const userId = 'user123'; // Replace with actual user ID
    mixpanel.identify(userId);
    mixpanel.people.set({ '$first_name': 'Test', '$last_name': 'User', 'plan': 'Free' });
    console.log(`Identified user: ${userId}`);
  };

  return (
    <SafeAreaView style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text style={{ fontSize: 24, marginBottom: 20 }}>Mixpanel React Native Demo</Text>
      <View style={{ gap: 10 }}>
        <Button title="Track 'App Loaded'" onPress={() => trackEvent('App Loaded')} />
        <Button title="Track 'Button Clicked'" onPress={() => trackEvent('Button Clicked')} />
        <Button title="Identify User" onPress={identifyUser} />
        <Button title="Reset Mixpanel" onPress={() => mixpanel.reset()} />
      </View>
    </SafeAreaView>
  );
}

view raw JSON →