@guidelytech/react-native 0.9.0 → 0.11.0

package/README.md

@@ -85,12 +85,77 @@ 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 |
 
 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).
+`launcherOffset` (default 72), `autocapture`, `appBuild`.
+
+## Product analytics (autocapture)
+
+The SDK records the same product-analytics events as the web SDK, so taps, time on screen and
+heatmaps show up in Pages, Heatmaps, Features, Funnels and Paths next to web clicks. Each capability
+runs when the project turns it on (Settings → Product analytics) and analytics are allowed
+(`analytics`, `consent`). The `autocapture` prop can only turn things off:
+
+```tsx
+<GuidelyProvider autocapture={{ clicks: false, heatmaps: false }} appVersion={version} appBuild={build} …>
+// autocapture={false} turns everything off, including screen page views, and removes the wrapper view
+```
+
+| Event | When | Properties |
+|---|---|---|
+| `click` | A tap on an interactive element | `selector`, `tag`, `text?`, `x`, `y`, `platform` |
+| `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` |
+| `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` |
+
+**Taps.** The provider wraps your app in a full-size `View` (`flex: 1`) with capture-phase touch
+handlers that only observe: they never claim the responder, stop propagation or delay anything. A
+tap is a single-finger touch that moves ≤ 10 pt and lasts < 1 s. Guidely's own UI (guide cards,
+launchers, messenger) is rendered outside the wrapper and never captured.
+
+**Selectors**, first match wins:
+
+1. A `<GuidelyTarget id>` / `useGuidelyTarget(id)` whose frame contains the tap (the smallest one) → `#<id>`.
+   The same id works in guides, Features and on the web (`data-guidely-id`), so this is the
+   recommended way to name what matters.
+2. The `nativeID` → `[nativeID="…"]`, then `testID` → `[testID="…"]` of the tapped interactive element.
+3. A short component path, innermost last: `Row:nth-of-type(3) > Pressable`.
+
+The interactive element is the innermost component with `onPress` / `onLongPress` (`Pressable`,
+`Touchable*`, `Button`, `Text onPress`, React Navigation buttons), else one with an interactive
+`accessibilityRole` / `role` (`button`, `link`, `tab`, `switch`, …). `tag` is its component name and
+`text` its visible text (else its accessibility label), whitespace collapsed, ≤ 100 characters.
+Taps on anything else record no `click` (they still count for rage taps and heatmaps). Text is
+never taken from a `TextInput`, and is left out inside `<GuidelyMask>` and when the project masks
+all text in replays:
+
+```tsx
+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.
+
+**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
+event. It is best-effort and guarded: when it is unavailable the tap still counts (heatmaps, rage
+taps, `#<id>` targets), and nothing ever throws into your app. Component names come from
+`displayName` / function names; Metro keeps function names by default, but a custom minifier that
+mangles them makes paths less readable — use `GuidelyTarget`, `nativeID` or `testID` for stable
+names. Taps handled entirely by native gesture recognizers (`react-native-gesture-handler` buttons,
+native-stack headers, some third-party native views) may not reach JavaScript touch handlers and are
+then not captured. Coordinates are relative to the React Native root view (the window in a
+full-screen app).
 
 ## Feature flags
 
@@ -150,4 +215,15 @@ the foreground; guides keep working offline. Events are queued, batched and retr
 session starts after the project's inactivity timeout. The SDK never throws into your app — errors
 go to `onError` and, with `debug`, the console.
 
+## Outages
+
+If Guidely is slow or down, your app keeps working. With a cached config the SDK waits at most
+1.5 s for the server at launch (config, then identify), starts from the cache, and applies the
+fresh answer when it arrives. Events, survey answers, guide completions/dismissals and checklist
+progress are queued and retried until the server takes them. After repeated failures the SDK backs
+off (5 s up to 5 min, or the server's `Retry-After`) and skips config refreshes until the API
+answers again. Scout replies give up when nothing arrives for 30 s, or when the stream goes quiet
+for 60 s. Pass `storage` (AsyncStorage) so queued events and answers survive an app restart;
+without it they are lost if the app is closed during an outage.
+
 Full guide: [docs/mobile.md](../../docs/mobile.md). Example app: `mobile/react-native/example`.