@nexly/react-native

React Native SDK for Nexly. Implements NexlyBase with:

• fetch({ keepalive: true }) transport,
• visitor/session IDs persisted via @react-native-async-storage/async-storage,
• device metadata via Platform, Dimensions, PixelRatio,
• engagement tracking driven by AppState (active seconds, heartbeat, session_ping).

Install

npm install @nexly/react-native @react-native-async-storage/async-storage

react and react-native must already be installed in your app.

Usage

import { NexlyProvider, useNexlyClient } from '@nexly/react-native'

export default function App() {
  return (
    <NexlyProvider appId="your-app-id" ingestKey="your-ingest-key" autoEngagement initialScreen="Home">
      <Root />
    </NexlyProvider>
  )
}

function Root() {
  const client = useNexlyClient()

  useEffect(() => {
    client?.screenview('Home')
  }, [client])

  return (
    <Button
      title="Upgrade"
      onPress={() => client?.event({ name: 'upgrade_clicked', type: 'custom', data: { plan: 'pro' } })}
    />
  )
}

Screens / paths

React Native has no URL, so Nexly uses a manual screen name instead:

• client.setScreen('Settings') — updates the screen used as path on future events.
• client.screenview('Settings') — sets the screen and sends a pageview.

Hook it up to your router of choice. Example with @react-navigation/native:

<NavigationContainer
  onStateChange={(state) => {
    const route = state?.routes[state.index ?? 0]
    if (route) client?.screenview(route.name)
  }}
>
  ...
</NavigationContainer>

Engagement

autoEngagement attaches an AppState listener that:

• Increments active_seconds only while the app is foregrounded.
• Sends a heartbeat every 60 s (lifecycle event for realtime dashboards).
• Sends session_ping when the app goes to background, and session_end on provider unmount.

No scroll/click tracking (those are DOM-only); if you want tap analytics, send custom engagement events yourself.

startEngagement() is idempotent — calling it again stops the previous subscription first, so Fast Refresh or double-mounts cannot produce duplicate listeners.