@guidelytech/react-native 0.16.0 → 0.17.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()`, `openArticle(articleId)`, `refresh()`, `setConsent()`, `on(event, cb)`, `getGuides()`, `getActiveGuide()`, `getState()`, `startSessionRecording()`, `stopSessionRecording()`, `isRecording()`, `getSessionId()` |
+| `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()`, `openArticle(articleId)`, `refresh()`, `setConsent()`, `on(event, cb)`, `getGuides()`, `getActiveGuide()`, `getState()`, `startSessionRecording()`, `stopSessionRecording()`, `isRecording()`, `getSessionId()`, `captureException(err, ctx?)`, `captureMessage(msg, level?)`, `addBreadcrumb()`, `setTag(s)`, `setExtra(s)`, `setContext()`, `setUser()` |
 | `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 |
@@ -91,7 +91,8 @@ Provider props: `projectId`, `apiUrl`, `environment`, `storage`, `user`, `debug`
 `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`, `sessionReplay`.
+`launcherOffset` (default 72), `autocapture`, `appBuild`, `sessionReplay`, `release`, `errors`
+(see [Errors and crashes](#errors-and-crashes)).
 
 ## Product analytics (autocapture)
 
@@ -165,6 +166,122 @@ 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).
 
+## Errors and crashes
+
+The SDK reports JavaScript errors with the same capture API as Sentry's SDKs, to the project's
+**Errors** page. Uncaught errors and unhandled promise rejections are captured automatically; caught
+ones with `captureException`.
+
+```tsx
+const guidely = useGuidely();
+try {
+  await pay(cart);
+} catch (err) {
+  guidely.captureException(err, { tags: { area: "checkout" }, extra: { cartSize: cart.length }, level: "error", fingerprint: ["{{ default }}", "checkout"], contexts: { payment: { provider: "stripe" } } });
+}
+guidely.captureMessage("Checkout took 30 s", "warning");
+guidely.setTag("plan", "pro");                         // setTags, setExtra, setExtras, setContext(name, ctx | null)
+guidely.setUser({ id: "u_42", email: "ana@example.com" }); // identify() + email/username on errors; null = reset()
+guidely.addBreadcrumb({ category: "cart", message: "Added item", data: { sku: "A1" } });
+```
+
+```tsx
+<GuidelyProvider
+  release="2.4.1"                 // default: the app version; must match --release of the source-map upload
+  errors={{
+    sampleRate: 1,                // 0–1, crashes included
+    ignoreErrors: ["Network request failed", /^AbortError: /],
+    denyUrls: [], allowUrls: [],  // against the innermost frame's file (app:///index.android.bundle)
+    beforeSend: ({ properties, detail }) => (properties.message.includes("ignore") ? null : { properties, detail }),
+    beforeBreadcrumb: (crumb) => (crumb.category === "console" ? null : crumb),
+    breadcrumbs: { console: true, http: true, navigation: true, taps: true, appLifecycle: true, guides: true }, // or false
+    captureErrors: true,          // false: no automatic capture (captureException still works)
+    dist: "512",                  // default: the app build number
+  }}
+  …
+>
+```
+
+Errors need the project's error tracking on (Settings → Privacy & data), `analytics` and consent:
+nothing leaves the device before consent is granted, errors captured while consent is `pending` are
+sent once it is granted and deleted when it is denied. The same error is sent at most 5 times per
+launch, and at most 50 errors per session (crashes always go out).
+
+**What is captured.** `ErrorUtils.setGlobalHandler` reports every uncaught JS error and then calls the
+handler that was installed before (React Native's own, which shows the red box in development and
+ends the app in release builds), with the same arguments, so nothing changes about how your app
+crashes. Fatal errors are `level: "fatal"`, `handled: false`, `mechanism: "onerror"`; non-fatal ones
+`level: "error"`. Unhandled promise rejections (`mechanism: "unhandledrejection"`, `level: "error"`)
+come from Hermes' rejection tracker. On JavaScriptCore pass React Native's Promise polyfill tracker:
+`errors={{ rejectionTracker: require("promise/setimmediate/rejection-tracking") }}`. In development
+the SDK keeps React Native's "Possible unhandled promise rejection" warning.
+
+**Crashes are saved first.** A fatal error ends a release app right after the handler, so the report
+is written to `storage` the moment it happens and sent on the next launch (which starts a new
+session; the crash keeps the session that crashed). React Native's handler is held back until the
+report is written and, when the network allows, sent — at most 2 s (`FATAL_FLUSH_MS`); in
+development it runs at once. AsyncStorage writes are asynchronous, so a report can still be lost if
+the OS ends the process before the write lands; a synchronous `storage` (an MMKV adapter) always has
+it. Without `storage` crash reports can't outlive the crash.
+
+**Breadcrumbs** (the last 100 ride along with each error): `navigation` (`screen()`), `ui.click`
+(taps, with the element's `selector`; never its text), `app.lifecycle` (`AppState`), `console`
+(`console.warn` / `console.error`), `fetch` / `xhr` (method, URL without query, status, duration;
+never Guidely's own requests; React Native's `fetch` runs on XMLHttpRequest and is recorded once, as
+`fetch`) and `guide` (guides shown, stepped through, completed, dismissed). Tap breadcrumbs need the
+provider's touch-observing wrapper (not with `autocapture={false}`).
+
+**Each event** carries `properties` (type, message, the innermost 30 frames, `platform: "javascript"`,
+`release`) and a Sentry-shaped `detail` (≤ 64 KB): the `cause` chain, breadcrumbs, tags, extra, user
+and contexts `os`, `device` (model from `expo-device` / `react-native-device-info`, or Android's own
+constants), `app` (version, build, foreground), `runtime` (`hermes` / `jsc`) and
+`react_native_context` (engine, React Native version, new architecture, Expo). Keys that look like
+credentials (`password`, `token`, `authorization`, `cookie`, …) are replaced with `[Filtered]`.
+
+**Stack traces.** Hermes release frames (`at pay (address at index.android.bundle:1:9876)`: line 1,
+column = bytecode offset) and JavaScriptCore frames (`pay@…/MyApp.app/main.jsbundle:1:2345`) are
+reported against `app:///index.android.bundle` / `app:///main.jsbundle`, whatever folder the app is
+installed in, so they map through source maps uploaded with `--url-prefix /`. Metro dev-server frames
+keep their URL. Engine built-ins (`(native)`, `InternalBytecode.js`) and `node_modules` frames are
+marked not in-app.
+
+### Uploading Hermes source maps
+
+Hermes needs the *composed* map (Metro's map combined with the Hermes bytecode map). Put the bundle and
+its map side by side in one folder and upload with the same release the app reports:
+
+```bash
+# Android: the release build composes the map; copy both next to each other
+mkdir -p build/sourcemaps
+cp android/app/build/generated/assets/react/release/index.android.bundle build/sourcemaps/
+cp android/app/build/generated/sourcemaps/react/release/index.android.bundle.map build/sourcemaps/
+
+# Or by hand (Android shown; iOS uses --platform ios and main.jsbundle)
+npx react-native bundle --platform android --dev false --entry-file index.js \
+  --bundle-output build/sourcemaps/index.android.bundle --sourcemap-output build/sourcemaps/index.android.packager.map
+node_modules/react-native/sdks/hermesc/osx-bin/hermesc -O -emit-binary -output-source-map \
+  -out=build/sourcemaps/index.android.bundle.hbc build/sourcemaps/index.android.bundle
+node node_modules/react-native/scripts/compose-source-maps.js \
+  build/sourcemaps/index.android.packager.map build/sourcemaps/index.android.bundle.hbc.map \
+  -o build/sourcemaps/index.android.bundle.map
+
+export GUIDELY_SOURCEMAP_KEY=gly_sk_…  GUIDELY_API_URL=https://<your Guidely API>
+npx @guidelytech/sourcemaps upload --dir build/sourcemaps --url-prefix / --release 2.4.1 --include .bundle.map
+# iOS (main.jsbundle + main.jsbundle.map): --include .jsbundle.map
+```
+
+On iOS, set `export SOURCEMAP_FILE="$DERIVED_FILE_DIR/main.jsbundle.map"` in the *Bundle React Native
+code and images* build phase; React Native then writes the composed map next to the build, and the
+bundle is `main.jsbundle` inside the `.app`. `--release` must equal the `release` prop (default: the
+app version, `CFBundleShortVersionString` / `versionName`).
+
+### Native crashes
+
+This SDK is pure JavaScript: it reports JavaScript errors only. Native crashes (signals,
+`NSException`, JVM exceptions, ANRs) are reported by Guidely's native iOS and Android SDKs, which the
+React Native SDK does not embed; capturing them in a React Native app means adding the native SDK
+to the iOS/Android projects as well and is not set up by this package yet.
+
 ## Session replay
 
 Records sessions for the dashboard's **Replays** player: masked screenshots (about one a second