How to add analytics to React Native

Analytics shows you how people use your React Native app on iOS and Android. This guide sets up Pieowl to track screen views, custom events and users. It takes about ten minutes.

The SDK adds the app version and build number to every event, plus the install referrer on Android. With two optional adapters, it also keeps events while the device is offline and sends them when it reconnects.

Prerequisites

• A React Native project (Expo or bare React Native)
• A Pieowl account (start a 14-day free trial)
• Your Client ID and Client Secret from the Pieowl dashboard

Install the SDK

Add the Pieowl React Native package and its Expo dependencies. The SDK uses expo-application for version data and expo-constants for the user agent.

npm install @pieowl/react-native
npx expo install expo-application expo-constants

pnpm and yarn work too. The Expo packages work in both Expo and bare React Native projects.

Initialize Pieowl

Create one Pieowl instance and use it across your app. React Native needs a clientSecret. A browser sends an origin that Pieowl can check, but a native app does not.

import { Pieowl } from '@pieowl/react-native';

export const pieowl = new Pieowl({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

Put this in a shared file like lib/pieowl.ts so you can import it anywhere. The SDK listens for app state changes and sets default properties like the version and build number.

Keep events while offline (optional)

By default, events are sent right away. To queue them while the device is offline, pass a NetInfo adapter. To keep the queue across app restarts, also pass an AsyncStorage adapter.

import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';
import { Pieowl } from '@pieowl/react-native';

export const pieowl = new Pieowl({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  networkInfo: NetInfo,
  storage: AsyncStorage,
});

When the device comes back online, the queue is sent.

Track screen views

To track screen views, hook into your navigation library. The setup depends on whether you use Expo Router or React Navigation.

With Expo Router, add the tracking call to your root layout. usePathname gives you the current route. useSegments gives you the route segments, which helps you group dynamic routes.

import { usePathname, useSegments } from 'expo-router';
import { useEffect } from 'react';
import { pieowl } from '@/lib/pieowl';

export default function RootLayout() {
  const pathname = usePathname();
  const segments = useSegments();

  useEffect(() => {
    pieowl.screenView(pathname, {
      segments: segments.join('/'),
    });
  }, [pathname, segments]);

  return (
    // Your layout JSX
  );
}

With React Navigation, track screen changes with the navigation container's callbacks. Create a navigation ref and pass a handler to onReady and onStateChange.

import { createNavigationContainerRef, NavigationContainer } from '@react-navigation/native';
import { pieowl } from '@/lib/pieowl';

const navigationRef = createNavigationContainerRef();

export function App() {
  const handleNavigationStateChange = () => {
    const current = navigationRef.getCurrentRoute();
    if (current) {
      pieowl.screenView(current.name, {
        params: current.params,
      });
    }
  };

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={handleNavigationStateChange}
      onStateChange={handleNavigationStateChange}
    >
      {/* Your navigators */}
    </NavigationContainer>
  );
}

onReady fires on first load, and onStateChange fires on every later navigation. Together they catch every screen view, including the first one.

Track custom events

Beyond screen views, track the actions that matter to your business. Call pieowl.track with an event name and optional properties.

import { pieowl } from '@/lib/pieowl';

function SignupButton() {
  const handlePress = () => {
    pieowl.track('button_clicked', {
      button_name: 'signup',
      screen: 'home',
    });
    // Continue with signup logic
  };

  return <Button onPress={handlePress} title="Sign Up" />;
}

Keep event names the same across your codebase. snake_case with a verb, like button_clicked or form_submitted, makes your data easier to read later.

You can also set global properties that are added to every event. Use them for data like the user's plan that you want on all events.

pieowl.setGlobalProperties({
  platform: Platform.OS,
  plan: user.plan,
});

Identify users

When a user logs in, link their activity to a profile. Then you can follow them across sessions and devices. Call pieowl.identify with the user's ID and any profile data you want to keep.

import { useEffect } from 'react';
import { pieowl } from '@/lib/pieowl';

function UserProfile({ user }) {
  useEffect(() => {
    if (user) {
      pieowl.identify({
        profileId: user.id,
        firstName: user.firstName,
        lastName: user.lastName,
        email: user.email,
        properties: {
          plan: user.plan,
        },
      });
    }
  }, [user]);

  return <Text>Welcome, {user?.firstName}!</Text>;
}

When the user logs out, call pieowl.clear(). New events are then not linked to the previous user.

function handleLogout() {
  pieowl.clear();
  // Continue with logout logic
}

Verify your setup

Run your app and move between a few screens. Tap the buttons you added tracking to. Then open the Pieowl dashboard and check the realtime view. Events should show up within seconds.

No events? Check the console in your React Native debugger, or the browser's developer tools if you use Expo web. The most common cause is a wrong Client ID or Client Secret. Make sure both match your dashboard. Remember that React Native needs the client secret, while the web SDKs do not.

Next steps

The React Native SDK reference covers more options. If you also build for the web, the JavaScript SDK uses the same tracking API, so your event names can stay the same everywhere.

Building a native iOS or Android app without React Native? Pieowl has no native Swift or Kotlin SDK, but you can send events over HTTP. See the Swift guide and the Kotlin guide.