feat(react-native): record automatic exception steps

.changeset/automatic-exception-steps-react-native.md

@@ -0,0 +1,10 @@
+---
+'@posthog/core': minor
+'posthog-react-native': minor
+---
+
+Add automatic exception steps to React Native, so a captured exception carries a timeline even where nobody called `addExceptionStep`. Set `errorTracking.exceptionSteps.automatic` to `true`, or to an object, to record a step for a screen change (`navigation`), an autocaptured tap (`taps`), or an app lifecycle transition (`lifecycle`). Every signal stays off by default, because each step adds bytes to every captured exception.
+
+Automatic steps carry `$type`, which the error tracking timeline already renders, and they share the byte-bounded buffer and the native forwarding that manual steps use. A manual step stays untyped. An event that `before_send` dropped leaves no step.
+
+`reset()` now clears the exception-step buffer, for automatic and manual steps alike. Exception steps are user-session state, so on a shared device the previous user's screen names and tap labels must not reach the next user's exception. The buffer still survives a capture, so every exception in one session carries the same steps.

examples/example-expo-53/app/(tabs)/error-tracking.tsx

@@ -112,6 +112,10 @@ export default function ErrorTrackingScreen() {
                     Record breadcrumb-style steps with addExceptionStep. Buffered steps attach to every captured
                     $exception as $exception_steps — including the manual captures above and the native crash below.
                 </ThemedText>
+                <ThemedText>
+                    This example also sets errorTracking.exceptionSteps.automatic, so switching tabs, tapping a button
+                    and backgrounding the app each leave their own step. Those steps carry a $type.
+                </ThemedText>
                 {EXCEPTION_STEPS.map(({ label, message, properties }) => (
                     <Button
                         key={label}

examples/example-expo-53/app/posthog.tsx

@@ -36,6 +36,11 @@ export const posthog = new PostHog(process.env.EXPO_PUBLIC_POSTHOG_PROJECT_API_K
             // `uploadNativeSymbols` option in app.json).
             nativeCrashes: true,
         },
+        exceptionSteps: {
+            // Record a step for every screen change, autocaptured tap and lifecycle transition, so a
+            // captured exception carries a timeline without an addExceptionStep call at each site.
+            automatic: true,
+        },
     },
     // Inject X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID on outgoing fetch
     // requests to these hostnames. Used by the Tracing Headers screen to verify

packages/core/src/error-tracking/exception-steps.spec.ts

@@ -3,6 +3,7 @@ import {
   ExceptionStep,
   ExceptionStepsBuffer,
   getUtf8ByteLength,
+  resolveAutomaticExceptionStepsConfig,
   resolveExceptionStepsConfig,
   stripReservedExceptionStepFields,
 } from './exception-steps'
@@ -24,6 +25,34 @@ describe('exception steps', () => {
     })
   })
 
+  describe('resolveAutomaticExceptionStepsConfig', () => {
+    const allOff = { navigation: false, taps: false, lifecycle: false }
+    const allOn = { navigation: true, taps: true, lifecycle: true }
+
+    it('disables every signal when no config is passed', () => {
+      expect(resolveAutomaticExceptionStepsConfig()).toEqual(allOff)
+      expect(resolveAutomaticExceptionStepsConfig(false)).toEqual(allOff)
+      expect(resolveAutomaticExceptionStepsConfig(null)).toEqual(allOff)
+    })
+
+    it('enables every signal for true', () => {
+      expect(resolveAutomaticExceptionStepsConfig(true)).toEqual(allOn)
+    })
+
+    it('enables only the signals the object sets', () => {
+      expect(resolveAutomaticExceptionStepsConfig({ navigation: true })).toEqual({ ...allOff, navigation: true })
+      expect(resolveAutomaticExceptionStepsConfig({ taps: true, lifecycle: true })).toEqual({
+        ...allOn,
+        navigation: false,
+      })
+    })
+
+    it('ignores a value that is neither a boolean nor an object', () => {
+      expect(resolveAutomaticExceptionStepsConfig('yes' as any)).toEqual(allOff)
+      expect(resolveAutomaticExceptionStepsConfig([] as any)).toEqual(allOff)
+    })
+  })
+
   describe('stripReservedExceptionStepFields', () => {
     it('strips reserved fields and keeps custom properties', () => {
       const result = stripReservedExceptionStepFields({
@@ -37,6 +66,18 @@ describe('exception steps', () => {
         droppedKeys: [EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE, EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP],
       })
     })
+
+    it('keeps a caller-provided $type and $level, which the SDK does not own', () => {
+      const result = stripReservedExceptionStepFields({
+        [EXCEPTION_STEP_INTERNAL_FIELDS.TYPE]: 'checkout',
+        [EXCEPTION_STEP_INTERNAL_FIELDS.LEVEL]: 'warning',
+      })
+
+      expect(result).toEqual({
+        sanitizedProperties: { $type: 'checkout', $level: 'warning' },
+        droppedKeys: [],
+      })
+    })
   })
 
   describe('ExceptionStepsBuffer', () => {

packages/core/src/error-tracking/exception-steps.ts

@@ -1,15 +1,34 @@
 import { isArray, isNumber, isObject, isString, safeJsonStringify } from '@/utils'
 
 export const EXCEPTION_STEP_INTERNAL_FIELDS = {
+  TYPE: '$type',
   MESSAGE: '$message',
+  LEVEL: '$level',
   TIMESTAMP: '$timestamp',
 } as const
 
+/**
+ * Only `$message` and `$timestamp` are reserved: the SDK owns their canonical values, so a caller
+ * cannot spoof them. `$type` and `$level` stay writable by callers who want to categorise their own
+ * steps, and the SDK sets `$type` itself only on automatic steps.
+ */
 const RESERVED_EXCEPTION_STEP_KEYS = new Set<string>([
   EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE,
   EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP,
 ])
 
+/**
+ * `$type` values the SDK sets on automatic steps. Every SDK uses these exact strings, so the error
+ * tracking timeline labels an automatic step the same way on web and on mobile.
+ */
+export const EXCEPTION_STEP_TYPES = {
+  NAVIGATION: 'navigation',
+  TAP: 'tap',
+  LIFECYCLE: 'lifecycle',
+} as const
+
+export type ExceptionStepType = (typeof EXCEPTION_STEP_TYPES)[keyof typeof EXCEPTION_STEP_TYPES]
+
 export type ExceptionStep = {
   [EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE]: string
   [EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP]: string | number
@@ -32,6 +51,62 @@ export const DEFAULT_EXCEPTION_STEPS_CONFIG: ResolvedExceptionStepsConfig = {
   max_bytes: 32768, // ~32KB
 }
 
+/**
+ * Which app signals the SDK turns into automatic steps. Every signal is opt-in, because a step adds
+ * bytes to each captured exception and the buffer already carries whatever the caller added by hand.
+ *
+ * NOTE: The SDK reads these signals from its own platform. A platform that cannot observe a signal
+ * ignores the flag rather than failing.
+ */
+export type AutomaticExceptionStepsConfig = {
+  /** Screen or route changes. @default false */
+  navigation?: boolean
+  /** Taps and clicks the SDK already autocaptures. @default false */
+  taps?: boolean
+  /** App lifecycle transitions such as open, foreground and background. @default false */
+  lifecycle?: boolean
+}
+
+export type ResolvedAutomaticExceptionStepsConfig = {
+  navigation: boolean
+  taps: boolean
+  lifecycle: boolean
+}
+
+export const DEFAULT_AUTOMATIC_EXCEPTION_STEPS_CONFIG: ResolvedAutomaticExceptionStepsConfig = {
+  navigation: false,
+  taps: false,
+  lifecycle: false,
+}
+
+const ALL_AUTOMATIC_EXCEPTION_STEPS_CONFIG: ResolvedAutomaticExceptionStepsConfig = {
+  navigation: true,
+  taps: true,
+  lifecycle: true,
+}
+
+/**
+ * Resolves the automatic-steps config. `true` enables every signal, `false` and `undefined` disable
+ * every signal, and an object enables only the signals it sets.
+ */
+export function resolveAutomaticExceptionStepsConfig(
+  config?: boolean | AutomaticExceptionStepsConfig | null
+): ResolvedAutomaticExceptionStepsConfig {
+  if (config === true) {
+    return { ...ALL_AUTOMATIC_EXCEPTION_STEPS_CONFIG }
+  }
+
+  if (!config || !isObject(config)) {
+    return { ...DEFAULT_AUTOMATIC_EXCEPTION_STEPS_CONFIG }
+  }
+
+  return {
+    navigation: config.navigation ?? DEFAULT_AUTOMATIC_EXCEPTION_STEPS_CONFIG.navigation,
+    taps: config.taps ?? DEFAULT_AUTOMATIC_EXCEPTION_STEPS_CONFIG.taps,
+    lifecycle: config.lifecycle ?? DEFAULT_AUTOMATIC_EXCEPTION_STEPS_CONFIG.lifecycle,
+  }
+}
+
 export function resolveExceptionStepsConfig(config?: ExceptionStepsConfig | null): ResolvedExceptionStepsConfig {
   if (!config) {
     return { ...DEFAULT_EXCEPTION_STEPS_CONFIG }

packages/node/references/posthog-node-references-latest.json

@@ -1727,6 +1727,28 @@
       ],
       "path": "src/types.ts"
     },
+    {
+      "id": "AutomaticExceptionStepsConfig",
+      "name": "AutomaticExceptionStepsConfig",
+      "properties": [
+        {
+          "description": "Screen or route changes.",
+          "type": "boolean",
+          "name": "navigation"
+        },
+        {
+          "description": "Taps and clicks the SDK already autocaptures.",
+          "type": "boolean",
+          "name": "taps"
+        },
+        {
+          "description": "App lifecycle transitions such as open, foreground and background.",
+          "type": "boolean",
+          "name": "lifecycle"
+        }
+      ],
+      "path": "../core/src/error-tracking/exception-steps.ts"
+    },
     {
       "id": "BaseException",
       "name": "BaseException",
@@ -2175,6 +2197,13 @@
       ],
       "path": "../core/src/error-tracking/exception-steps.ts"
     },
+    {
+      "id": "ExceptionStepType",
+      "name": "ExceptionStepType",
+      "properties": [],
+      "path": "../core/src/error-tracking/exception-steps.ts",
+      "example": "(typeof EXCEPTION_STEP_TYPES)[keyof typeof EXCEPTION_STEP_TYPES]"
+    },
     {
       "id": "ExpressErrorMiddleware",
       "name": "ExpressErrorMiddleware",
@@ -3851,6 +3880,25 @@
       "path": "../core/src/error-tracking/coercers/promise-rejection-event.ts",
       "example": "PromiseRejectionEventLike | EventWithDetailReason"
     },
+    {
+      "id": "ResolvedAutomaticExceptionStepsConfig",
+      "name": "ResolvedAutomaticExceptionStepsConfig",
+      "properties": [
+        {
+          "type": "boolean",
+          "name": "navigation"
+        },
+        {
+          "type": "boolean",
+          "name": "taps"
+        },
+        {
+          "type": "boolean",
+          "name": "lifecycle"
+        }
+      ],
+      "path": "../core/src/error-tracking/exception-steps.ts"
+    },
     {
       "id": "ResolvedExceptionStepsConfig",
       "name": "ResolvedExceptionStepsConfig",

packages/react-native/references/posthog-react-native-references-latest.json

@@ -2239,6 +2239,28 @@
       ],
       "path": "dist/error-tracking/index.d.ts"
     },
+    {
+      "id": "AutomaticExceptionStepsConfig",
+      "name": "AutomaticExceptionStepsConfig",
+      "properties": [
+        {
+          "description": "Screen or route changes.",
+          "type": "boolean",
+          "name": "navigation"
+        },
+        {
+          "description": "Taps and clicks the SDK already autocaptures.",
+          "type": "boolean",
+          "name": "taps"
+        },
+        {
+          "description": "App lifecycle transitions such as open, foreground and background.",
+          "type": "boolean",
+          "name": "lifecycle"
+        }
+      ],
+      "path": "../core/src/error-tracking/exception-steps.ts"
+    },
     {
       "id": "BaseException",
       "name": "BaseException",
@@ -2593,6 +2615,11 @@
       "id": "ExceptionStepsOptions",
       "name": "ExceptionStepsOptions",
       "properties": [
+        {
+          "description": "Records steps for app signals the SDK already observes, so an exception carries a timeline even where nobody called `addExceptionStep`. Every signal is off by default, because each step adds bytes to every captured exception.\nPass `true` to enable every signal, or an object to enable single signals.\nfalse",
+          "type": "boolean | CoreErrorTracking.AutomaticExceptionStepsConfig",
+          "name": "automatic"
+        },
         {
           "description": "Whether exception steps are recorded and attached.   true",
           "type": "boolean",
@@ -2606,6 +2633,13 @@
       ],
       "path": "dist/error-tracking/index.d.ts"
     },
+    {
+      "id": "ExceptionStepType",
+      "name": "ExceptionStepType",
+      "properties": [],
+      "path": "../core/src/error-tracking/exception-steps.ts",
+      "example": "(typeof EXCEPTION_STEP_TYPES)[keyof typeof EXCEPTION_STEP_TYPES]"
+    },
     {
       "id": "FeatureFlagDetail",
       "name": "FeatureFlagDetail",
@@ -4333,6 +4367,25 @@
       "path": "../core/src/error-tracking/coercers/promise-rejection-event.ts",
       "example": "PromiseRejectionEventLike | EventWithDetailReason"
     },
+    {
+      "id": "ResolvedAutomaticExceptionStepsConfig",
+      "name": "ResolvedAutomaticExceptionStepsConfig",
+      "properties": [
+        {
+          "type": "boolean",
+          "name": "navigation"
+        },
+        {
+          "type": "boolean",
+          "name": "taps"
+        },
+        {
+          "type": "boolean",
+          "name": "lifecycle"
+        }
+      ],
+      "path": "../core/src/error-tracking/exception-steps.ts"
+    },
     {
       "id": "ResolvedExceptionStepsConfig",
       "name": "ResolvedExceptionStepsConfig",