@akhilpulse/samadhaan-session-replay

React Native SDK for embedding Samadhaan Guided Support into your mobile app — session recording, live remote screen-share, take-control, and guided-tour overlays.

The SDK talks to the Samadhaan dashboard at https://samadhaan.pulseenergy.io by default.

Install

npm install @akhilpulse/samadhaan-session-replay react-native-view-shot @react-native-async-storage/async-storage

iOS:

cd ios && pod install

Usage

import { SessionReplayProvider } from "@akhilpulse/samadhaan-session-replay";

export default function App() {
  return (
    <SessionReplayProvider
      config={{
        // serverUrl is optional — defaults to https://samadhaan.pulseenergy.io
        appId: "app_xxx",
        user: { userId: "user_123", email: "[email protected]" },
        appVersion: "1.4.2",
      }}
    >
      <YourApp />
    </SessionReplayProvider>
  );
}

To point at a staging/self-hosted dashboard, pass serverUrl:

<SessionReplayProvider
  config={{
    serverUrl: "https://staging-samadhaan.pulseenergy.io",
    appId: "app_xxx",
  }}
>

Privacy masking

Wrap any subtree to redact it from screenshots:

import { PrivacyLayer } from "@akhilpulse/samadhaan-session-replay";

<PrivacyLayer redact>
  <CreditCardForm />
</PrivacyLayer>

Pause / resume

import { useSessionReplay } from "@akhilpulse/samadhaan-session-replay";

const { pause, resume, sessionId, status } = useSessionReplay();

What it does

• Creates a session against POST /api/guided-support/sessions and persists sessionId in AsyncStorage so it can be resumed after relaunch.
• Captures gestures (tap, swipe) using a passive PanResponder + onTouchEnd bubble listener — host taps still work.
• Captures screenshots every 10 s in background mode, every 200 ms in live mode, via react-native-view-shot. Uploads via POST /api/guided-support/storage/uploads/request-url then PUTs to the returned URL.
• Auto-connects to WS /ws/guided-support?sessionId=…&role=device&token=… when the dashboard flips the session to live.
• Streams binary frames as [ts u32 BE | width u16 BE | height u16 BE] + JPEG bytes.
• Renders a remote-control overlay that visualizes incoming taps. Native touch dispatch (iOS UIEvent / Android AccessibilityService) is wired by the integrator via a small custom native module.
• Auto-mounts a guided-tour overlay (singleton-guarded). On guided_tour_request, shows an inline absolutely-positioned consent prompt (NOT <Modal> — RN Modals leave a stale native window that swallows touches). On accept, renders a thin glowing edge halo (4 strips with pointerEvents: "none") plus a small centered "End Tour" pill. Streams the agent's pointer as a red laser-pointer dot.
• Pauses screenshot capture while the iOS keyboard is visible.

Critical constraints (don't skip)

1. Never use RN <Modal> for transient consent UI — use absolutely-positioned <View> (no zIndex — see #6).
2. Never animate colors with useNativeDriver: false — causes 60fps JS commits that break touch handling on Fabric.
3. The guided-tour overlay must NOT cover the screen center. Use 4 thin edge strips with pointerEvents: "none".
4. Pause screenshot capture while the iOS keyboard is visible.
5. Auto-mount the guided-tour overlay inside the provider, and singleton-guard it.
6. Android elevated views & screenshots. react-native-view-shot uses a software canvas draw on Android (view.draw(canvas)) which silently skips any view promoted to a hardware compositor layer (anything with elevation > 0 or zIndex > 0 — RN implements zIndex via setElevation on Android). To work around this, starting in 0.3.0 the SDK ships its own native module that captures via Android's PixelCopy API (real on-screen pixels, including hardware layers, modals, FABs, and native SurfaceViews like react-native-maps). This module is autolinked — after upgrading the SDK on Android you must rebuild the app (cd android && ./gradlew clean && cd .. && npx react-native run-android) for the new screenshot path to activate. If the native module isn't present at runtime (older build, Expo Go), the SDK transparently falls back to captureScreen and the elevation limitation re-applies. Requires Android 7.0+ (API 24).

Publishing

This package is set up for the @akhilpulse npm scope.

# 1. Make sure you're logged in to npm with publish rights to @akhilpulse
npm login

# 2. From the mobile-sdk/ directory:
npm install
npm run build      # compiles src/ → dist/ via tsc
npm publish        # uses publishConfig.access = "restricted"

To bump the version:

npm version patch   # or minor / major
npm publish

See src/SessionReplayProvider.tsx for the full implementation.