Add deeplinkIntegration for automatic deep link breadcrumbs (#5983)

* feat(core): add deeplinkIntegration for automatic deep link breadcrumbs

Introduces a new `deeplinkIntegration` that automatically captures breadcrumbs
whenever the app is opened or foregrounded via a deep link.

- Intercepts cold-start links via `Linking.getInitialURL()`
- Intercepts warm-open links via `Linking.addEventListener('url', ...)`
- Breadcrumbs use `category: 'deeplink'` and `type: 'navigation'`
- Respects `sendDefaultPii`: when false, query strings are stripped and
  numeric / UUID / long-hex path segments are replaced with `<id>`
- Compatible with both Expo Router and plain React Navigation deep linking
  (uses the standard RN `Linking` API, no framework-specific dependencies)
- Gracefully skips setup when Linking is unavailable (e.g. web)

Closes #5424

* docs: add changelog entry for deeplinkIntegration

* fix(core): Address review feedback in deeplinkIntegration

- Strip URL fragments (#) in addition to query strings when sendDefaultPii
  is off, preventing PII leaks via fragment identifiers
- Store the Linking event listener subscription and remove it on client
  close to prevent resource leaks and duplicate breadcrumbs on hot reload
- Cache getBreadcrumbUrl result to avoid redundant getClient lookups and
  regex sanitization
- Extract RNLinking and LinkingSubscription interfaces for cleaner types
- Add tests for fragment stripping, combined query+fragment stripping,
  and subscription cleanup on client close

* refactor(core): Reuse existing sanitizeUrl from tracing/utils in deeplinkIntegration

Replace the duplicated stripQueryAndFragment/sanitizeUrl logic with the
existing exported sanitizeUrl from tracing/utils.ts, which already strips
query strings and fragments. The deeplink-specific ID replacement regex
is kept in a new sanitizeDeepLinkUrl wrapper.

* fix(core): Fix hostname corruption and repeated setup leak in deeplinkIntegration

- Split URL into authority and path before applying ID-replacement regex
  so hostnames that resemble hex strings (e.g. myapp://deadbeef/...) are
  not incorrectly replaced with <id>
- Move subscription to the factory closure and remove it on repeated
  setup calls to prevent duplicate listeners when Sentry.init() is
  called more than once
- Add tests for hostname preservation and repeated setup cleanup

* style: Fix lint issues in deeplinkIntegration

* style: Move interfaces to top and attach JSDoc to tryGetLinking

* fix(core): Rename Linking variable to avoid duplicate declaration in compiled output

The local variable 'Linking' from tryGetLinking() collided with the
destructured 'Linking' from require('react-native') in the compiled JS,
causing a 'Duplicate declaration' build error. Renamed to 'linking'.

* fix(core): Fix Linking duplicate declaration and revert unrelated replay-stubs.jar

- Rename destructured Linking to rnLinking inside tryGetLinking to avoid
  Babel/Metro duplicate declaration errors in compiled output
- Fix getInitialURL call chain formatting per lint
- Revert unrelated replay-stubs.jar binary change

* fix(core): Use direct property access for Linking to avoid Babel duplicate declaration

Replace destructured import with direct property access on require result
as suggested by @antonis to fix the persisting Babel/Metro build error.

Author: alwx

CHANGELOG.md

@@ -12,6 +12,7 @@
 
 - Enable "Open Sentry" button in Playground for Expo apps ([#5947](https://github.com/getsentry/sentry-react-native/pull/5947))
 - Add `attachAllThreads` option to attach full stack traces for all threads to captured events on iOS ([#5960](https://github.com/getsentry/sentry-react-native/issues/5960))
+- Add `deeplinkIntegration` for automatic deep link breadcrumbs ([#5983](https://github.com/getsentry/sentry-react-native/pull/5983))
 - Name navigation spans using dispatched action payload when `useDispatchedActionData` is enabled ([#5982](https://github.com/getsentry/sentry-react-native/pull/5982))
 
 ### Fixes

packages/core/src/js/integrations/deeplink.ts

@@ -0,0 +1,144 @@
+import type { IntegrationFn } from '@sentry/core';
+
+import { addBreadcrumb, defineIntegration, getClient } from '@sentry/core';
+
+import { sanitizeUrl } from '../tracing/utils';
+
+export const INTEGRATION_NAME = 'DeepLink';
+
+interface LinkingSubscription {
+  remove: () => void;
+}
+
+interface RNLinking {
+  getInitialURL: () => Promise<string | null>;
+  addEventListener: (event: string, handler: (event: { url: string }) => void) => LinkingSubscription;
+}
+
+/**
+ * Replaces dynamic path segments (UUID-like or numeric values) with a placeholder
+ * to avoid capturing PII in path segments when `sendDefaultPii` is off.
+ *
+ * Only replaces segments that look like identifiers (all digits, UUIDs, or hex strings).
+ */
+function sanitizeDeepLinkUrl(url: string): string {
+  const stripped = sanitizeUrl(url);
+
+  // Split off the scheme+authority (e.g. "myapp://host") so the regex
+  // only operates on the path and cannot corrupt the hostname.
+  const authorityEnd = stripped.indexOf('/', stripped.indexOf('//') + 2);
+  if (authorityEnd === -1) {
+    return stripped;
+  }
+
+  const authority = stripped.slice(0, authorityEnd);
+  const path = stripped.slice(authorityEnd);
+
+  // Replace path segments that look like dynamic IDs:
+  // - Numeric segments (e.g. /123)
+  // - UUID-formatted segments (e.g. /a1b2c3d4-e5f6-7890-abcd-ef1234567890)
+  // - Hex strings ≥8 chars (e.g. /deadbeef1234)
+  const sanitizedPath = path.replace(
+    /\/([0-9]+|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{8,})(?=\/|$)/gi,
+    '/<id>',
+  );
+
+  return authority + sanitizedPath;
+}
+
+/**
+ * Returns the URL to include in the breadcrumb, respecting `sendDefaultPii`.
+ * When PII is disabled, query strings and ID-like path segments are removed.
+ */
+function getBreadcrumbUrl(url: string): string {
+  const sendDefaultPii = getClient()?.getOptions()?.sendDefaultPii ?? false;
+  return sendDefaultPii ? url : sanitizeDeepLinkUrl(url);
+}
+
+function addDeepLinkBreadcrumb(url: string): void {
+  const breadcrumbUrl = getBreadcrumbUrl(url);
+  addBreadcrumb({
+    category: 'deeplink',
+    type: 'navigation',
+    message: breadcrumbUrl,
+    data: {
+      url: breadcrumbUrl,
+    },
+  });
+}
+
+const _deeplinkIntegration: IntegrationFn = () => {
+  let subscription: LinkingSubscription | undefined;
+
+  return {
+    name: INTEGRATION_NAME,
+    setup(client) {
+      const linking = tryGetLinking();
+
+      if (!linking) {
+        return;
+      }
+
+      // Remove previous subscription if setup is called again (e.g. repeated Sentry.init)
+      subscription?.remove();
+
+      // Cold start: app opened via deep link
+      linking
+        .getInitialURL()
+        .then((url: string | null) => {
+          if (url) {
+            addDeepLinkBreadcrumb(url);
+          }
+        })
+        .catch(() => {
+          // Ignore errors from getInitialURL
+        });
+
+      // Warm open: deep link received while app is running
+      subscription = linking.addEventListener('url', (event: { url: string }) => {
+        if (event?.url) {
+          addDeepLinkBreadcrumb(event.url);
+        }
+      });
+
+      client.on('close', () => {
+        subscription?.remove();
+        subscription = undefined;
+      });
+    },
+  };
+};
+
+/**
+ * Attempts to import React Native's Linking module without a hard dependency.
+ * Returns null if not available (e.g. in web environments).
+ */
+function tryGetLinking(): RNLinking | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return (require('react-native') as { Linking: RNLinking }).Linking ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Integration that automatically captures breadcrumbs when deep links are received.
+ *
+ * Intercepts links via React Native's `Linking` API:
+ * - `getInitialURL` for cold starts (app opened via deep link)
+ * - `addEventListener('url', ...)` for warm opens (link received while running)
+ *
+ * Respects `sendDefaultPii`: when disabled, query params and ID-like path segments
+ * are stripped from the URL before it is recorded.
+ *
+ * Compatible with both Expo Router and plain React Navigation deep linking.
+ *
+ * @example
+ * ```ts
+ * Sentry.init({
+ *   integrations: [deeplinkIntegration()],
+ * });
+ * ```
+ */
+export const deeplinkIntegration = defineIntegration(_deeplinkIntegration);

packages/core/src/js/integrations/exports.ts

@@ -29,6 +29,7 @@ export { primitiveTagIntegration } from './primitiveTagIntegration';
 export { logEnricherIntegration } from './logEnricherIntegration';
 export { graphqlIntegration } from './graphql';
 export { supabaseIntegration } from './supabase';
+export { deeplinkIntegration } from './deeplink';
 
 export {
   browserApiErrorsIntegration,