React Native | Pieowl

Looking for a step-by-step tutorial? Read the React Native analytics guide.

Installation

Install dependencies

The SDK uses expo-application for the app version and build number (and the install referrer on Android), and expo-constants to get the user agent.

bash

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

Initialize

Native apps can't send CORS headers, so the SDK authenticates with your client secret.

typescript

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

const pieowl = new Pieowl({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

Options

Common options

apiUrl - The URL of the Pieowl API (default: https://api.pieowl.com). Change it only to send events through your own proxy
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, events are queued and not sent until you call ready() (useful for consent)

Usage

Track event

typescript

pieowl.track('my_event', { foo: 'bar' });

typescript

import { usePathname, useSegments } from 'expo-router';

const pieowl = new Pieowl({ /* ... */ })

function RootLayout() {
  // ...
  const pathname = usePathname()
  // Segments is optional but can be nice to have if you
  // want to group routes together
  // pathname = /posts/123
  // segments = ['posts', '[id]']
  const segments = useSegments()

  useEffect(() => {
    // Simple
    pieowl.screenView(pathname)

    // With extra data
    pieowl.screenView(pathname, {
      // segments is optional but nice to have
      segments: segments.join('/'),
      // other optional data you want to send with the screen view
    })
  }, [pathname,segments])
  // ...
}

tsx

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

  const pieowl = new Pieowl({ /* ... */ })
  const navigationRef = createNavigationContainerRef()

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

    return (
      <NavigationContainer
        ref={navigationRef}
        onReady={handleNavigationStateChange}
        onStateChange={handleNavigationStateChange}
      >
        <Stack.Navigator />
      </NavigationContainer>
    )
  }

For all other methods, see the JavaScript SDK.

Offline support

The SDK can hold events while the device is offline and send them when it's back online. Each queued event gets a timestamp when it fires, so it's recorded at the right time even if it arrives later.

Two optional peer dependencies enable this feature:

bash

npm install @react-native-async-storage/async-storage @react-native-community/netinfo

Pass them to the constructor:

typescript

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

const pieowl = new Pieowl({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
  // Persist the event queue across app restarts
  storage: AsyncStorage,
  // Automatically flush the queue when the device comes back online
  networkInfo: NetInfo,
});

What each option does:

networkInfo — tells the SDK when the device goes offline, so events are queued instead of sent, and sends the queue as soon as the device is back online.
storage — saves the queue to disk, so queued events survive an app restart.

The SDK also tries to send the queue each time the app becomes active.