React Native SDKBeta

Analytics SDK for React Native with React hooks, offline queue, and React Navigation integration.

Requirements

React Native 0.70+React 18+iOS 13+Android 5+

Installation

Install the SDK and its required peer dependency.

terminal

npm install @himetrica/tracker-react-native @react-native-async-storage/async-storage

Peer Dependencies

@react-native-async-storage/async-storage — Persistent storage for visitor ID, session, and offline queue
@react-navigation/native — Optional, for automatic screen tracking

Install with AI

Copy this prompt and paste it into ChatGPT, Claude, or any AI assistant to install the React Native SDK for you.

Install Himetrica analytics in my React Native app. Himetrica is a React Native analytics SDK with offline support.

1. Install the packages:
npm install @himetrica/tracker-react-native @react-native-async-storage/async-storage

2. Wrap your app with HimetricaProvider:
import { HimetricaProvider } from '@himetrica/tracker-react-native/react'

export default function App() {
  return (
    <HimetricaProvider apiKey="YOUR_API_KEY">
      <Navigation />
    </HimetricaProvider>
  )
}

3. For automatic screen tracking with React Navigation:
import { useHimetricaNavigation } from '@himetrica/tracker-react-native/react'

const { ref, onReady, onStateChange } = useHimetricaNavigation()

<NavigationContainer ref={ref} onReady={onReady} onStateChange={onStateChange}>
  ...
</NavigationContainer>

4. Track custom events:
import { useTrackEvent } from '@himetrica/tracker-react-native/react'
const trackEvent = useTrackEvent()
trackEvent('purchase_completed', { product_id: 'pro_plan', price: 9.99 })

5. Identify users after login:
import { useHimetrica } from '@himetrica/tracker-react-native/react'
const himetrica = useHimetrica()
await himetrica.identify({ userId: user.externalId, name: user.name, email: user.email })

The userId parameter is optional but enables cross-device visitor merging — when two visitors identify with the same userId, they are automatically merged into one.

6. If your app has login/logout, call reset() on logout to start a fresh visitor before identifying the next user:
await himetrica.reset()

The SDK requires React Native 0.70+, React 18+, and @react-native-async-storage/async-storage. It handles offline queuing and session management automatically. Errors can be captured manually with captureError() and captureMessage().

Initialization

Wrap your app with the provider or use the client directly.

App.tsx

// App.tsx
import { HimetricaProvider } from '@himetrica/tracker-react-native/react'

export default function App() {
  return (
    <HimetricaProvider apiKey="YOUR_API_KEY">
      <Navigation />
    </HimetricaProvider>
  )
}

Screen Tracking

Track screen views with the useTrackScreen hook.

import { useTrackScreen } from '@himetrica/tracker-react-native/react'

function ProfileScreen() {
  useTrackScreen('Profile')

  return <View>...</View>
}

// With a custom path
function ProductScreen({ id }: { id: string }) {
  useTrackScreen('Product', `/products/${id}`)

  return <View>...</View>
}

Screen duration is automatically tracked when users navigate away or the app goes to background.

React Navigation Integration

Automatically track screen changes with React Navigation using useHimetricaNavigation.

App.tsx

import { NavigationContainer } from '@react-navigation/native'
import { useHimetricaNavigation } from '@himetrica/tracker-react-native/react'

function App() {
  const { ref, onReady, onStateChange } = useHimetricaNavigation()

  return (
    <HimetricaProvider apiKey="YOUR_API_KEY">
      <NavigationContainer
        ref={ref}
        onReady={onReady}
        onStateChange={onStateChange}
      >
        <Stack.Navigator>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen name="Profile" component={ProfileScreen} />
        </Stack.Navigator>
      </NavigationContainer>
    </HimetricaProvider>
  )
}

How it works

Listens to navigation state changes and extracts the active route name
Deduplicates consecutive navigations to the same screen
Supports nested navigators — resolves the deepest active route

Event Tracking

Track custom events and user interactions.

import { useTrackEvent } from '@himetrica/tracker-react-native/react'

function CheckoutButton() {
  const trackEvent = useTrackEvent()

  return (
    <Button
      title="Purchase"
      onPress={() => {
        trackEvent('purchase_completed', {
          product_id: 'pro_plan',
          price: 9.99,
          currency: 'USD',
        })
      }}
    />
  )
}

User Identification

Associate analytics with a user after authentication.

import { useHimetrica } from '@himetrica/tracker-react-native/react'

function OnLogin() {
  const himetrica = useHimetrica()

  async function handleLogin(user: User) {
    await himetrica.identify({
      userId: user.externalId,   // optional — stable external user ID
      name: user.name,
      email: user.email,
      metadata: {
        plan: user.subscriptionPlan,
        signup_date: user.createdAt,
      },
    })
  }
}

The userId parameter is optional but enables cross-device visitor merging. When two visitors identify with the same userId, they are automatically merged into one.

Error Tracking

Capture errors manually in your catch blocks, or use the error boundary component to catch React render errors.

// Capture errors manually in your catch blocks:
import { useCaptureError } from '@himetrica/tracker-react-native/react'

function PaymentForm() {
  const captureError = useCaptureError()

  async function handlePayment() {
    try {
      await processPayment()
    } catch (error) {
      captureError(error as Error, { screen: 'Payment' })
    }
  }
}

Configuration

All configuration options available as provider props or constructor arguments.

App.tsx

import { HimetricaProvider } from '@himetrica/tracker-react-native/react'

<HimetricaProvider
  apiKey="YOUR_API_KEY"
  apiUrl="https://app.himetrica.com"  // Custom API URL
  autoTrackScreens={true}             // Auto-track with React Navigation
  sessionTimeout={30 * 60 * 1000}     // 30 minutes
  enableLogging={false}               // Debug logging
  maxQueueSize={1000}                 // Max offline queue size
  flushInterval={30}                  // Flush interval in seconds
>

Property	Default	Description
apiKey	required	Your Himetrica API key
apiUrl	app.himetrica.com	Custom API endpoint
autoTrackScreens	true	Auto-track screen views
sessionTimeout	1800000	Session expiry in ms (30 min)
enableLogging	false	Enable debug logging
maxQueueSize	1000	Max queued events for offline
flushInterval	30	Queue flush interval in seconds

Features

Offline Support

Events are queued in AsyncStorage and sent when connectivity is restored.

Session Management

Automatic session handling with configurable timeout and app lifecycle awareness.

Duration Tracking

Automatic time-on-screen measurement, including app background transitions.

React Navigation

Drop-in integration with React Navigation for automatic screen tracking.

API Reference

Method	Description
trackScreen(name, path?)	Track a screen view
track(event, properties?)	Track a custom event
identify({userId?, name, email, metadata})	Identify the current user. Pass userId for cross-device merging.
captureError(error, context?)	Manually capture an error
captureMessage(msg, severity?, ctx?)	Capture a log message
getVisitorId()	Get the current visitor ID
reset()	Clear all stored data and start a fresh visitor. Call on logout before identifying a new user.
flush()	Force flush event queue
destroy()	Clean up listeners and timers

Also see

iOS & macOS SDK

Also see

Web Tracker