@guidelytech/react-native 0.12.0 → 0.14.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`,
+`consent` (`granted` / `pending` / `denied`), `appVersion` (overrides the detected version, see below), `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)
 
@@ -111,7 +111,7 @@ runs when the project turns it on (Settings → Product analytics) and analytics
 | `rage_click` | 3+ taps within 1 s and 30 pt | the `click` properties of the tapped (or hit) view + `count` |
 | `heatmap` | Every 40 taps, on screen change and when the app goes to the background | `path?`, `viewportWidth`, `viewportHeight`, `pageHeight`, `platform`, `points` |
 | `page_leave` | The screen changes or the app goes to the background | `path?`, `screen`, `durationMs`, `scrollDepth: 100`, `platform` |
-| `page_view` | `screen()` with a new name; after returning to the foreground with `resumed: true` | `path`, `screen`, `platform` |
+| `page_view` | `screen()` with a new name; after returning to the foreground with `resumed: true` | `path`, `screen`, `platform`, `deviceType`, `os`, `osVersion` |
 | `app_install` / `app_update` | First launch / a launch with a new `appVersion` or `appBuild` | `appVersion`, `build`, `previousVersion`, `previousBuild` |
 | `app_open` / `app_background` | Cold start and return to the foreground / background | `coldStart` / `foregroundMs` |
 
@@ -141,10 +141,18 @@ import { GuidelyMask } from "@guidelytech/react-native";
 <GuidelyMask><Pressable onPress={showCard}><Text>{cardNumber}</Text></Pressable></GuidelyMask>
 ```
 
-**App lifecycle.** `app_install` / `app_update` need the `appVersion` prop (e.g.
-`Application.nativeApplicationVersion` from `expo-application`; `appBuild` from
-`nativeBuildVersion`) and `storage`; the last version is stored per public key. An app that already
-had Guidely installed stores its version silently on the first launch with this release.
+**App and OS versions.** The SDK detects them on iOS and Android. The OS version (`18.1`, or `14` on
+Android) comes from React Native and is sent as `osVersion` on `page_view` and as the `osVersion`
+flag attribute. React Native has no API for the app's own version and build, so they are read from
+the first linked native module that knows them: `@guidelytech/react-native-replay`
+(`CFBundleShortVersionString` / `versionName`, `CFBundleVersion` / `versionCode`), then
+`expo-application` (not in Expo Go, which reports its own version), then `react-native-device-info`.
+If none of these is installed, pass `appVersion` / `appBuild`. Passing them also overrides the
+detected values.
+
+**App lifecycle.** `app_install` / `app_update` need a known app version (detected or the
+`appVersion` prop) and `storage`. The last version is stored per public key. An app that already had
+Guidely installed stores its version silently on the first launch with this release.
 
 **Limitations.** React Native has no public API for "which component is under this point", so
 element resolution (steps 2 and 3, `tag`, `text`) reads React's internal component tree of the touch
@@ -157,6 +165,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:
@@ -179,7 +225,7 @@ useGuidely().isFeatureEnabled("new-checkout"); // or getFeatureValue / getFeatur
 
 Flags evaluate on the device with `id` (user id, else the anonymous id), `anonymousId`, identify
 traits, `account`, `$audiences`, `screen`, `path`, `platform` (`ios` / `android`), `deviceType`,
-`appVersion`, `locale` and `environment`, plus `flagAttributes` from the provider. The last payload
+`appVersion`, `osVersion`, `locale` and `environment`, plus `flagAttributes` from the provider. The last payload
 is kept in `storage`, so flags work offline from a cold start; they refresh when the app returns to
 the foreground. Experiment exposures are tracked as `experiment_viewed` events.