Helpr React Native Cobrowse

React Native and Expo SDK for Helpr Visual Assist and chat.

Install

npm install @helprso/react-native react-native-webview

For Expo apps, install the WebView peer with Expo's version-aware installer:

npx expo install react-native-webview

Usage

The SDK automatically discovers the React Native fiber root on mount. For best performance, import the register entry before React loads — this enables commit-driven snapshots (faster screen updates). Without it, co-browse still works using interval-based capture.

Standard Expo / bare RN (recommended)

// index.ts  (set "main": "index.ts" in package.json)
import '@helprso/react-native/register';
import { registerRootComponent } from 'expo';
import App from './App';

registerRootComponent(App);

Expo Router (recommended)

Expo Router's default entry (expo-router/entry) loads React before your route files run. For commit-driven snapshots, create a custom entry file:

// index.js  (set "main": "index.js" in package.json)
import '@helprso/react-native/register';
import 'expo-router/entry';

If you place the register import in app/_layout.tsx instead, co-browse still works but snapshot updates are interval-based rather than commit-driven.

import * as Crypto from 'expo-crypto';
import * as SecureStore from 'expo-secure-store';
import {
  HelprCobrowseProvider,
  HelprChatProvider,
} from '@helprso/react-native';

const config = {
  apiBase: 'https://www.helpr.so',
  widgetKey: 'YOUR_WIDGET_KEY',
  appName: 'Acme Mobile',
  getRandomValues: (bytes: Uint8Array) => Crypto.getRandomValues(bytes),
  storage: SecureStore,
};

export default function App() {
  return (
    <HelprCobrowseProvider config={config}>
      <HelprChatProvider>
        <RootNavigator />
      </HelprChatProvider>
    </HelprCobrowseProvider>
  );
}

getRandomValues is optional. The SDK first uses the app-provided provider, then globalThis.crypto.getRandomValues, then a hidden WebView backed by browser WebCrypto. Helpr never falls back to Math.random for E2E encryption keys or IVs.

storage is optional, but a host-provided adapter is recommended. Without one, the SDK uses an internal hidden WebView localStorage fallback so anonymous visitor continuity can survive app reloads on platforms where WebView storage persists. Use an explicit adapter such as SecureStore or AsyncStorage when you need deterministic retention, reset behavior, or encrypted-at-rest visitor data.

Native map and plain WebView surfaces are treated as opaque by default in co-browse replay. Native maps render as lightweight SVG schematics from their region/marker/polyline props when possible; plain WebViews render as layout-preserving placeholders unless they are wrapped with HelprWebView. Use visualFallback.components for other opaque native components, or visualFallback.mapMode: 'placeholder', visualFallback: { mode: 'block' }, or visualFallback.blockComponents for stricter privacy.

Snapshots use snapshotInterval while idle in a co-browse session. During remote interaction/annotation consent, the SDK also runs a temporary faster cadence controlled by controlSnapshotInterval (default 500 ms, minimum 250 ms, set 0 to disable) so app-side changes feel more live without increasing idle battery/network use.

Push Notifications

The SDK can register an Expo push token so Helpr can notify the same visitor when an agent replies while the app is closed or offline. The host app still owns native notification permissions and token creation.

import * as Notifications from 'expo-notifications';
import { Platform } from 'react-native';
import { useCobrowse } from '@helprso/react-native';

function PushBridge() {
  const cobrowse = useCobrowse();

  useEffect(() => {
    let mounted = true;
    (async () => {
      const { status } = await Notifications.requestPermissionsAsync();
      if (status !== 'granted') return;
      const token = (await Notifications.getExpoPushTokenAsync()).data;
      if (!mounted) return;
      await cobrowse.setPushToken({
        token,
        provider: 'expo',
        platform: Platform.OS === 'ios' ? 'ios' : 'android',
      });
    })();
    return () => { mounted = false; };
  }, [cobrowse]);

  return null;
}

You can also pass push in CobrowseConfig when the token is already available. Tokens are tied to the SDK visitor ID and, when identity is present, to Helpr's hashed userId/email identity keys. Helpr only sends visitor pushes for public agent/bot replies when the visitor WebSocket is not online.

Full reference: https://helpr.so/docs/mobile-sdk