React Native SDK

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({ name: user.name, email: user.email })

The SDK requires React Native 0.70+, React 18+, and @react-native-async-storage/async-storage. It handles offline queuing, session management, and error capture automatically.

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.

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({
      name: user.name,
      email: user.email,
      metadata: {
        plan: user.subscriptionPlan,
        signup_date: user.createdAt,
      },
    })
  }
}

Error Tracking

Errors are captured automatically. You can also capture them manually or use the error boundary component.

// Automatic error tracking is enabled by default.
// You can also capture errors manually:

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
  autoTrackErrors={true}              // Capture uncaught errors
  sessionTimeout={30 * 60 * 1000}     // 30 minutes
  enableLogging={false}               // Debug logging
  maxQueueSize={1000}                 // Max offline queue size
  flushInterval={30}                  // Flush interval in seconds
>
PropertyDefaultDescription
apiKeyrequiredYour Himetrica API key
apiUrlapp.himetrica.comCustom API endpoint
autoTrackScreenstrueAuto-track screen views
autoTrackErrorstrueCapture uncaught errors
sessionTimeout1800000Session expiry in ms (30 min)
enableLoggingfalseEnable debug logging
maxQueueSize1000Max queued events for offline
flushInterval30Queue 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

MethodDescription
trackScreen(name, path?)Track a screen view
track(event, properties?)Track a custom event
identify({name, email, metadata})Identify the current user
captureError(error, context?)Manually capture an error
captureMessage(msg, severity?, ctx?)Capture a log message
getVisitorId()Get the current visitor ID
flush()Force flush event queue
destroy()Clean up listeners and timers

Also see

iOS & macOS SDK

Also see

Web Tracker

Himetrica - Analytics That Actually Matter