@guidelytech/react-native 0.12.0 → 0.13.0

package/README.md

@@ -76,7 +76,7 @@ tasks).
 
 | | |
 |---|---|
-| `useGuidely()` | Client: `identify(id, traits?, account?)`, `setAccount`, `updateTraits`, `reset()`, `track(name, props?)`, `screen(name)`, `startGuide(idOrKey)`, `stopGuide()`, `dismissGuide()`, `openChecklist(key)`, `closeChecklist(key)`, `completeChecklistTask(key, taskId)`, `openResourceCenter()`, `closeResourceCenter()`, `refresh()`, `setConsent()`, `on(event, cb)`, `getGuides()`, `getActiveGuide()`, `getState()` |
+| `useGuidely()` | Client: `identify(id, traits?, account?)`, `setAccount`, `updateTraits`, `reset()`, `track(name, props?)`, `screen(name)`, `startGuide(idOrKey)`, `stopGuide()`, `dismissGuide()`, `openChecklist(key)`, `closeChecklist(key)`, `completeChecklistTask(key, taskId)`, `openResourceCenter()`, `closeResourceCenter()`, `refresh()`, `setConsent()`, `on(event, cb)`, `getGuides()`, `getActiveGuide()`, `getState()`, `startSessionRecording()`, `stopSessionRecording()`, `isRecording()`, `getSessionId()` |
 | `useGuidelyReady()` | `true` once config is loaded |
 | `useGuidelyIdentify(id, traits?, account?)` | Identify when the signed-in user changes |
 | `useGuidelyScreen(name)` | Report a screen view from a component |
@@ -85,13 +85,13 @@ tasks).
 | `useChecklistProgress(key)`, `useGuideState(key)`, `useActiveGuide()` | Live state |
 | `<GuidelyTarget id>`, `useGuidelyTarget(id)` | Guide targets |
 | `<GuidelyScreenScope name>`, `guidelyScreenLayout` | Screen scoping for targets |
-| `<GuidelyMask>` | Keeps its children's text out of tap analytics |
+| `<GuidelyMask>` | Keeps its children out of tap-analytics text and session recordings (it sets its own `nativeID`) |
 
 Provider props: `projectId`, `apiUrl`, `environment`, `storage`, `user`, `debug`, `analytics`,
 `consent` (`granted` / `pending` / `denied`), `appVersion` (for *App version* rules), `theme`,
 `configRefreshMs`, `onNavigate`, `onError`, `showChecklistLauncher` (default `true`),
 `showResourceCenterLauncher` (default `false`), `showMessengerLauncher` (default `true`), `insets`,
-`launcherOffset` (default 72), `autocapture`, `appBuild`.
+`launcherOffset` (default 72), `autocapture`, `appBuild`, `sessionReplay`.
 
 ## Product analytics (autocapture)
 
@@ -157,6 +157,44 @@ native-stack headers, some third-party native views) may not reach JavaScript to
 then not captured. Coordinates are relative to the React Native root view (the window in a
 full-screen app).
 
+## Session replay
+
+Records sessions for the dashboard's **Replays** player: masked screenshots (about one a second
+while the screen changes), touches, screen views and Guidely events. Screenshots need native code,
+so they come from a separate package; the SDK itself stays pure JavaScript (and works in Expo Go
+without it).
+
+```bash
+npm install @guidelytech/react-native-replay   # then rebuild: expo prebuild / pod install / gradle
+```
+
+```tsx
+<GuidelyProvider projectId="pk_prod_xxx" sessionReplay={{ enabled: true, maskAllText: true }} …>
+```
+
+Recording needs both this option and *Session replay* turned on in the project settings, plus
+analytics consent; the project's sample rate picks which sessions are recorded, and
+`useGuidely().startSessionRecording()` / `stopSessionRecording()` force a session on or off.
+
+**Masking** happens on the device before a frame is encoded. `TextInput`s are always painted over;
+`maskAllText` (or the project's *mask all text* setting) covers every `Text`, `maskAllImages` every
+`Image`, and `<GuidelyMask>` anything inside it. The keyboard is never recorded. Targets named in the
+project's block selectors (`#<guidely id>`) are masked too. `maskAllText` also keeps text out of tap
+analytics. Note that `<GuidelyMask>` hides its content from recordings, so wrap only what is
+sensitive, not the whole app.
+
+| Option | Default | |
+|---|---|---|
+| `enabled` | `false` | Record sessions |
+| `maskAllText` | `false` | Paint over all text |
+| `maskAllImages` | `false` | Paint over all images |
+| `captureIntervalMs` | `1000` | Time between screenshots (min 500) |
+
+Captures pause while a finger is down, follow 200 ms after it lifts and slow to one every 4 s while
+the screen is idle. Chunks upload every 10 s and when the app goes to the background. iOS draws the
+app's windows; Android uses `PixelCopy` (Android 8.0+), so `SurfaceView` content (some map views)
+records as blank and `FLAG_SECURE` screens as a grey frame.
+
 ## Feature flags
 
 Built in, with the same `projectId` — nothing to configure: