@engagex/react-native

React Native SDK for EngageX tracking. Persists an anonymous id, buffers events offline-safe and posts them to your tracking host — with <EngageProvider>, sendEngageEvent(), engageIdentify() and trackScreen().

Unlike the web SDK, React Native has no browser, so this package is a full ingest client (it does not load engage.v1.js). It talks to the same POST /v1/collect endpoint with your public key.

Install

npm add @engagex/react-native @react-native-async-storage/async-storage

@react-native-async-storage/async-storage is required (it persists the anonymous id + the offline event queue).

Use a mobile source key. Mobile apps have no Origin header, so the source must not have an origin allowlist (unlike web sources).

Setup

// App.tsx
import { EngageProvider } from '@engagex/react-native'

export default function App() {
  return (
    <EngageProvider publicKey="pk_mobile_xxx">
      {/* ...your app... */}
    </EngageProvider>
  )
}

You only pass publicKey — the tracking host is baked in (override with host for self-hosting / dev).

Track events

import { sendEngageEvent, engageIdentify, trackScreen } from '@engagex/react-native'

// business / behavioural event
sendEngageEvent('order.placed', { order_id: 'DH1', total: 1990000 })

// identify — resolving key (phone/email, ≥1) + optional traits + consent
engageIdentify({ phone: '0912345678', name: 'An' }, { consent: true })

// screen view
trackScreen('ProductDetail', { product_id: 88 })

Auto screen tracking with React Navigation

There is no History API on mobile, so wire trackScreen to your navigator:

import { NavigationContainer } from '@react-navigation/native'
import { trackScreen } from '@engagex/react-native'

const navRef = useNavigationContainerRef()

<NavigationContainer
  ref={navRef}
  onStateChange={() => {
    const route = navRef.getCurrentRoute()
    if (route) trackScreen(route.name, route.params)
  }}
>
  {/* ...screens... */}
</NavigationContainer>

Notes

• Offline-safe: events persist to AsyncStorage and re-queue if a send fails; they flush on an interval and when the app goes to background.
• Identity: not shared with the web _cdp_tid (different device). Cross-device stitching happens server-side when you engageIdentify with the same phone/email.
• Events use the same taxonomy as web, but use screen.viewed instead of page.viewed.

API

| Export | Description | | --- | --- | | <EngageProvider publicKey host? context? /> | Init the client. Mount once at the root. | | sendEngageEvent(event, properties?) | Queue a track event. | | engageIdentify(identity, consent?) | Queue an identify. | | trackScreen(screen, properties?) | Shortcut for sendEngageEvent('screen.viewed', ...). | | engageFlush() | Force-flush the buffer now. |

License

MIT