React Native SDK

Full reference for @onramp-sdk/react-native. Works with bare React Native and Expo (managed and bare workflow).

Installation

npm install @onramp-sdk/react-native
# or
yarn add @onramp-sdk/react-native

No native modules are required. The SDK uses only JavaScript APIs (AsyncStorage via @react-native-async-storage/async-storage).

Setup

Call OnRamp.init() once when your app starts - before any OnRamp.step() calls. A good place is the root App component.

import { useEffect } from 'react'
import { OnRamp } from '@onramp-sdk/react-native'

export default function App() {
  useEffect(() => {
    OnRamp.init({ apiKey: 'onr_xxxxxxxxxxxx' })
  }, [])

  return (
    <NavigationContainer>
      <RootStack />
    </NavigationContainer>
  )
}

Your API key is on the Settings page of each app in the dashboard. It looks like onr_a3f8d2e1b9c4....

OnRamp.init() options

Tracking steps

OnRamp.step(name, options?)

Records a funnel milestone. Safe to call anywhere - the SDK queues events if the network is unavailable and flushes when connectivity returns.

import { OnRamp } from '@onramp-sdk/react-native'

// Basic
OnRamp.step('account_created')

// With custom properties
OnRamp.step('subscription_started', {
  properties: {
    plan: 'pro',
    billing_period: 'annual',
    price_usd: 79.99,
  },
})

Options

Screen tracking

Navigation adapter (React Navigation)

Wrap your NavigationContainer with NavigationTracker to automatically record every screen change:

import { NavigationContainer } from '@react-navigation/native'
import { NavigationTracker } from '@onramp-sdk/react-native'

export default function App() {
  useEffect(() => {
    OnRamp.init({ apiKey: 'onr_xxxxxxxxxxxx' })
  }, [])

  return (
    <NavigationTracker>
      <NavigationContainer>
        <RootStack />
      </NavigationContainer>
    </NavigationTracker>
  )
}

Each screen change is recorded as a navigation event with the route name. These appear in session timelines and the journey map but do not count toward funnel step conversion.

Identifying users

OnRamp.identify(traits)

Associates the current anonymous user with known identity traits. Call once after sign-in so integrations (Stripe, RevenueCat) can match the user to external records.

import { OnRamp } from '@onramp-sdk/react-native'

// After the user signs in
OnRamp.identify({ email: user.email, userId: user.id })

identify() is entirely optional. All funnel and retention features work without it. Only call it if you have an integration connected and want to correlate OnRamp sessions with external revenue data.

Session management

OnRamp.newSession()

Force-starts a new session - useful after logout so the next user gets a clean session.

async function handleLogout() {
  await signOut()
  OnRamp.newSession()
}

App lifecycle

The SDK automatically tracks app foreground/background transitions using AppState. These are visible in session timelines and used to detect session boundaries.

You do not need to add any lifecycle listeners yourself.

TypeScript

The SDK ships full TypeScript types. No @types/ package needed.

import { OnRamp } from '@onramp-sdk/react-native'

function trackPayment(amount: number): void {
  OnRamp.step('payment_completed', {
    properties: { amount_cents: Math.round(amount * 100) },
  })
}

Offline support

Events are batched and queued in AsyncStorage when the device is offline. The queue is flushed automatically when connectivity is restored. The queue holds up to 500 events; older events are dropped if this limit is exceeded without a connection.