Mobile SDKs

Overview

The Helpr React Native SDK mirrors the web widget protocol for native apps. It connects through the same widget init endpoint, subscribes to the same visitor WebSocket channel, sends the same identity/custom/event/tag/card context, and renders chat with the same team theme settings.

Use it for fully native screens, fully WebView-based apps, and mixed native/WebView apps. Native views are serialized from the React Native view tree; wrapped web content should use HelprWebView so the SDK can capture the DOM and keep page metadata current.

Platform Support

Installation

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

react-native-webview is a peer dependency. If your app uses Expo and does not already have the peer packages, install them with Expo's version-aware installer:

npx expo install react-native-webview

Quick Start

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

Standard Expo / bare React Native

// 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

Expo Router’s default 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';

Then wrap your app once at the top level. Put HelprChatProvider inside HelprCobrowseProvider.

import React from 'react';
import { Platform } from 'react-native';
import * as Device from 'expo-device';
import {
  HelprCobrowseProvider,
  HelprChatProvider,
} from '@helprso/react-native';

const helprConfig = {
  apiBase: 'https://www.helpr.so',
  widgetKey: 'YOUR_WIDGET_KEY',
  appName: 'Acme Mobile',
  appVersion: '1.0.0',
  page: {
    title: 'Home',
    url: 'acme://home',
  },
  deviceInfo: {
    os: Platform.OS === 'ios' ? 'iOS' : 'Android',
    osVersion: String(Platform.Version || ''),
    brand: Device.brand || '',
    model: Device.modelName || '',
  },
};

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

The SDK initializes the visitor, opens the main visitor WebSocket, sends heartbeats, tracks app focus, and waits for chat or co-browse activity.

Provider Order

HelprCobrowseProvider owns the visitor session, WebSocket connection, identity store, and co-browse capture. HelprChatProvider consumes that session to render chat UI and notification state.

<HelprCobrowseProvider config={helprConfig}>
  <HelprChatProvider>
    {/* useCobrowse() and useHelprChat() are available here */}
    <AppScreens />
  </HelprChatProvider>
</HelprCobrowseProvider>

HelprChatProvider

The chat provider renders the modal chat sheet, top notification banner, unread state, read receipts, and optional floating chat button.

<HelprChatProvider
  notificationBar
  notificationDurationMs={5000}
  chatBubbleVisible={false}
  hasCustomChatTrigger
>
  <RootNavigator />
</HelprChatProvider>

useHelprChat()

Use useHelprChat() to open, close, and inspect the native chat UI from any child component.

import {
  useHelprChat,
  chatBubbleIcon,
} from '@helprso/react-native';

function SupportButton() {
  const chat = useHelprChat();

  return (
    <Pressable onPress={chat.open}>
      <Image
        source={chatBubbleIcon}
        style={{ width: 22, height: 22, tintColor: chat.themeColor }}
      />
      {chat.unreadCount > 0 && (
        <Text>{chat.unreadCount > 9 ? '9+' : chat.unreadCount}</Text>
      )}
    </Pressable>
  );
}

HelprChatView

Use HelprChatView when chat should be embedded inside a support screen instead of opened as a modal.

import { HelprChatView } from '@helprso/react-native';

function SupportScreen({ navigation }) {
  return (
    <View style={{ flex: 1 }}>
      <HelprChatView
        style={{ flex: 1 }}
        onUnreadCount={(count) => console.log('unread', count)}
        onClose={() => navigation.goBack()}
      />
    </View>
  );
}

Notifications & Unread State

Incoming agent messages are received on the main visitor WebSocket. The provider increments unread count, shows a top banner, and sends a chat_read receipt when the user opens chat.

• If the floating bubble is visible, unread count is shown on the bubble.
• If the bubble is hidden and no custom trigger is registered, the SDK only shows a floating chat button while unread messages are pending.
• If hasCustomChatTrigger is true, the SDK does not render a floating entry point. Your trigger should read unreadCount from useHelprChat().
• On app launch, unread state is seeded from widget init when an active chat can be resumed.

Custom Triggers

Use a custom trigger when the host app already has a support tab, header action, or profile-menu item for chat.

<HelprChatProvider hasCustomChatTrigger>
  <AppScreens />
</HelprChatProvider>

function HeaderHelpButton() {
  const chat = useHelprChat();

  return (
    <Pressable onPress={chat.open} accessibilityRole="button">
      <Text>Help</Text>
      {chat.unreadCount > 0 && <Text>{chat.unreadCount}</Text>}
    </Pressable>
  );
}

Native Co-browse Capture

When an agent starts visual assist, the SDK captures the React Native view hierarchy, layout, scroll state, taps, and screen changes, then streams a live representation of the app to Helpr. Pure native screens do not require HelprWebView.

The provider sends an initial screen snapshot, then batches incremental updates after relevant UI commits. Agents can see native screens and layout changes without video capture, screenshots, or per-screen setup.

Security & Bandwidth

Mobile Visual Assist uses the same zero-knowledge security model as the Helpr web widget. All visual assist traffic runs over WebSocket Secure: the main visitor WSS channel handles presence, chat, and visitor context, while a dedicated visual assist WSS channel carries the co-browse stream.

Screen content is end-to-end encrypted between the visitor app and the agent before it reaches Helpr’s relay. The session uses per-session P-256 key exchange, HKDF-SHA-256 key derivation, and AES-256-GCM message encryption. Larger screen payloads are gzip-compressed before encryption.

Because Helpr streams structured screen updates instead of video frames or repeated screenshots, bandwidth stays much lower than pixel-streaming tools. Typical active visual assist sessions average roughly 10-50 KB/s after the initial snapshot, with short bursts during large screen transitions. Video or screenshot-based co-browse tools commonly use hundreds of KB/s to multiple MB/s for the same session.

HelprWebView

Use HelprWebView instead of react-native-webview’s raw WebView for any web content you want represented accurately in co-browse.

import { HelprWebView } from '@helprso/react-native';

function StorefrontScreen() {
  return (
    <HelprWebView
      source={{ uri: 'https://example.com/account' }}
      style={{ flex: 1 }}
      cobrowseId="account-webview"
    />
  );
}

HelprWebView forwards normal WebView props and adds DOM capture, safe-area CSS normalization, scroll geometry, and automatic page metadata updates from location.href and document.title.

Consent Hooks

Teams can require visitor consent before visual assist starts or before an agent can interact. The SDK exposes async hooks for host-app prompts.

const helprConfig = {
  apiBase: 'https://www.helpr.so',
  widgetKey: 'YOUR_WIDGET_KEY',
  onViewConsentRequest: async ({ agentName }) => {
    return showConfirm(`${agentName || 'An agent'} wants to view your screen`);
  },
  onInteractConsentRequest: async ({ agentName }) => {
    return showConfirm(`${agentName || 'An agent'} wants to interact`);
  },
};

Control Metadata

The mobile SDK preserves interaction metadata in the co-browse stream so remote-control features can target the same native elements the user can interact with. Visual replay still uses positioned DOM nodes to match React Native layout; controls are described with metadata instead of browser-default button/link markup.

For built-in React Native interactions, the SDK records the exact handler surface it sees on the React fiber tree. This includes onPress, onLongPress, onPressIn, onPressOut, responder handlers, touch handlers, and scroll handlers. Metadata is inherited from composite wrappers such as Pressable and TouchableOpacity onto the native host view, then serialized as role, data-helpr-interactive, data-helpr-interactions, data-helpr-component, and data-helpr-native-tag.

Set normal accessibility props whenever possible. accessibilityRole="button", accessibilityRole="link", labels, disabled state, and similar props make the replay clearer for agents and give the control layer better intent.

<Pressable
  accessibilityRole="button"
  accessibilityLabel="Apply discount code"
  onPress={applyDiscount}
>
  <Text>Apply</Text>
</Pressable>

For custom gesture systems or domain-specific controls, add non-executable action names with helprActions or helprControlActions. The SDK only transports the action names; it never serializes or runs your function bodies.

<MealCard
  meal={meal}
  onPress={() => openMeal(meal.id)}
  onSwipeLeft={() => skipMeal(meal.id)}
  helprControlActions={['openMeal', 'swipeLeft', 'pinchZoomImage']}
/>

Masking & Blocking

Use capture controls to avoid exposing sensitive input values or entire components during co-browse.

const helprConfig = {
  apiBase: 'https://www.helpr.so',
  widgetKey: 'YOUR_WIDGET_KEY',
  maskProps: ['secureTextEntry'],
  blockComponents: ['PaymentCardForm', 'SSNInput'],
};

Page Metadata

Page metadata controls what agents see as the visitor’s current page or native screen. Web pages inside HelprWebView are detected automatically. Native screens should set metadata from your navigation layer.

The SDK automatically detects native screen transitions, but page metadata is also an explicit navigation hint. Calling setPage() on real route changes starts the mobile Visitor is navigating state immediately and uses the fastest page-change snapshot path, so the agent view switches cleanly to the new screen. Avoid calling it on every render or for transient UI such as bottom sheets unless that UI is a real page-level destination.

import { useHelprPage, useHelprRoutePage } from '@helprso/react-native';

function LoginScreen() {
  useHelprPage({
    title: 'Sign in',
    url: 'acme://login',
  });

  return <LoginForm />;
}

function ProductScreen({ route }) {
  useHelprRoutePage(route, { scheme: 'acme' }, [route.name]);
  return <ProductDetails />;
}

You can also call setPage() directly from useCobrowse(), for example in a central navigation ref.

const cobrowse = useCobrowse();

navigationRef.addListener('state', () => {
  const route = navigationRef.getCurrentRoute();
  cobrowse.setPage({
    title: route?.name || 'App',
    url: `acme://${route?.name || 'app'}`,
  });
});

Identity

identify() sets the current visitor’s identity and merges with previously stored identity fields. The SDK follows the same reserved fields as the JavaScript widget: email, name, userId, userHash, and company.

import { useCobrowse } from '@helprso/react-native';

function AccountBootstrap({ user }) {
  const cobrowse = useCobrowse();

  useEffect(() => {
    cobrowse.identify({
      email: user.email,
      name: user.fullName,
      userId: user.id,
      userHash: user.helprHash,
      company: {
        name: user.company.name,
        plan: user.company.plan,
        mrr: user.company.mrr,
      },
    });
  }, [cobrowse, user]);

  return null;
}

Push Notifications

The SDK can register an Expo push token so Helpr can notify the visitor when an agent replies while the app is closed or offline. The host app 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, Helpr’s hashed userId / email identity keys.

Custom Data

setCustom() attaches arbitrary traits to the visitor. They appear in the agent sidebar and are included in visitor context.

const cobrowse = useCobrowse();

cobrowse.setCustom({
  subscription: 'enterprise',
  trialEnds: '2026-05-01',
  features: ['sso', 'api', 'webhooks'],
});

Initial identity, custom data, tags, and cards can also be passed through CobrowseConfig. Runtime calls merge into persisted SDK storage.

Events, Tags, Cards

The SDK sends the same visitor context primitives as the web widget.

const cobrowse = useCobrowse();

cobrowse.track('checkout_completed', {
  total: 99.0,
  items: 3,
});

await cobrowse.tag('vip');
await cobrowse.untag('trial');

cobrowse.setCards([
  {
    type: 'text',
    title: 'Subscription',
    body: 'Enterprise plan, renewal due May 31',
  },
]);

Reset

Call reset() on logout to clear identity, custom data, tags, cards, queued events, and the stored visitor ID. The SDK reconnects as a fresh visitor.

async function handleLogout() {
  await cobrowse.reset();
  await auth.logout();
}

CobrowseConfig

Exports

Auto-Captured Data

Widget Protocol Parity

The native SDK follows the web widget’s visitor flow:

1. Calls /api/widget/init with key, vid, optional group, touch: 1, and platform: 'mobile-sdk'.
2. Uses the returned visitor channel, token, widget color, bubble position, visibility, assist WebSocket, and resumable chat state.
3. Subscribes to the main visitor WebSocket channel with the returned token.
4. Publishes visitor_heartbeat with page, device, geo, identity, custom data, tags, and widget state.
5. Publishes visitor_track, visitor_tags, visitor_cards, and chat read receipts as state changes.
6. Listens for assist invites, interact invites, visitor remaps, chat activation, chat messages, proactive messages, and chat end events.

Full Example

import React, { useEffect } from 'react';
import { Image, Platform, Pressable, Text, View } from 'react-native';
import * as Device from 'expo-device';
import {
  HelprCobrowseProvider,
  HelprChatProvider,
  HelprWebView,
  chatBubbleIcon,
  useCobrowse,
  useHelprChat,
  useHelprRoutePage,
} from '@helprso/react-native';

const helprConfig = {
  apiBase: 'https://www.helpr.so',
  widgetKey: 'YOUR_WIDGET_KEY',
  appName: 'Acme Mobile',
  appVersion: '1.0.0',
  page: { title: 'Home', url: 'acme://home' },
  deviceInfo: {
    os: Platform.OS === 'ios' ? 'iOS' : 'Android',
    osVersion: String(Platform.Version || ''),
    brand: Device.brand || '',
    model: Device.modelName || '',
  },
  maskProps: ['secureTextEntry'],
};

export default function App() {
  return (
    <HelprCobrowseProvider config={helprConfig}>
      <HelprChatProvider hasCustomChatTrigger>
        <HomeScreen route={{ name: 'Home' }} />
      </HelprChatProvider>
    </HelprCobrowseProvider>
  );
}

function HomeScreen({ route }) {
  const cobrowse = useCobrowse();
  const chat = useHelprChat();

  useHelprRoutePage(route, { scheme: 'acme' }, [route.name]);

  useEffect(() => {
    cobrowse.identify({
      email: '[email protected]',
      name: 'Jane Smith',
      userId: 'usr_123',
    });
    cobrowse.setCustom({ plan: 'enterprise' });
    cobrowse.tag('mobile-user');
  }, [cobrowse]);

  return (
    <View style={{ flex: 1 }}>
      <HelprWebView
        source={{ uri: 'https://example.com/account' }}
        style={{ flex: 1 }}
      />
      <Pressable onPress={chat.open}>
        <Image
          source={chatBubbleIcon}
          style={{ width: 22, height: 22, tintColor: chat.themeColor }}
        />
        {chat.unreadCount > 0 && <Text>{chat.unreadCount}</Text>}
      </Pressable>
    </View>
  );
}