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

alwx · alwx · commit f8614a8d623b · 2026-04-13T16:09:22.000+02:00
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
diff --git a/packages/core/src/js/integrations/deeplink.ts b/packages/core/src/js/integrations/deeplink.ts
@@ -0,0 +1,117 @@
+import type { IntegrationFn } from '@sentry/core';
+import { addBreadcrumb, defineIntegration, getClient } from '@sentry/core';
+
+export const INTEGRATION_NAME = 'DeepLink';
+
+/**
+ * Strips the query string from a URL.
+ */
+function stripQueryString(url: string): string {
+  const queryIndex = url.indexOf('?');
+  return queryIndex !== -1 ? url.slice(0, queryIndex) : url;
+}
+
+/**
+ * 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 sanitizeUrl(url: string): string {
+  const withoutQuery = stripQueryString(url);
+
+  // 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)
+  return withoutQuery.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>',
+  );
+}
+
+/**
+ * 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 : sanitizeUrl(url);
+}
+
+function addDeepLinkBreadcrumb(url: string): void {
+  addBreadcrumb({
+    category: 'deeplink',
+    type: 'navigation',
+    message: getBreadcrumbUrl(url),
+    data: {
+      url: getBreadcrumbUrl(url),
+    },
+  });
+}
+
+const _deeplinkIntegration: IntegrationFn = () => {
+  return {
+    name: INTEGRATION_NAME,
+    setup(_client) {
+      const Linking = tryGetLinking();
+
+      if (!Linking) {
+        return;
+      }
+
+      // 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
+      Linking.addEventListener('url', (event: { url: string }) => {
+        if (event?.url) {
+          addDeepLinkBreadcrumb(event.url);
+        }
+      });
+    },
+  };
+};
+
+/**
+ * Attempts to import React Native's Linking module without a hard dependency.
+ * Returns null if not available (e.g. in web environments).
+ */
+function tryGetLinking(): { getInitialURL: () => Promise<string | null>; addEventListener: (event: string, handler: (event: { url: string }) => void) => void } | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Linking } = require('react-native') as { Linking: { getInitialURL: () => Promise<string | null>; addEventListener: (event: string, handler: (event: { url: string }) => void) => void } };
+    return 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);
diff --git a/packages/core/src/js/integrations/exports.ts b/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,
diff --git a/packages/core/test/integrations/deeplink.test.ts b/packages/core/test/integrations/deeplink.test.ts
@@ -0,0 +1,199 @@
+import { addBreadcrumb, getClient } from '@sentry/core';
+
+import { deeplinkIntegration } from '../../src/js/integrations/deeplink';
+
+const mockGetInitialURL = jest.fn<Promise<string | null>, []>();
+const mockAddEventListener = jest.fn<{ remove: () => void }, [string, (event: { url: string }) => void]>();
+
+jest.mock('react-native', () => ({
+  Linking: {
+    getInitialURL: (...args: unknown[]) => mockGetInitialURL(...args),
+    addEventListener: (...args: Parameters<typeof mockAddEventListener>) => mockAddEventListener(...args),
+  },
+}));
+
+jest.mock('@sentry/core', () => {
+  const actual = jest.requireActual('@sentry/core');
+  return {
+    ...actual,
+    addBreadcrumb: jest.fn(),
+    getClient: jest.fn(),
+  };
+});
+
+const mockAddBreadcrumb = addBreadcrumb as jest.Mock;
+const mockGetClient = getClient as jest.Mock;
+
+describe('deeplinkIntegration', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockGetInitialURL.mockResolvedValue(null);
+    mockAddEventListener.mockReturnValue({ remove: jest.fn() });
+    mockGetClient.mockReturnValue({
+      getOptions: () => ({ sendDefaultPii: false }),
+    });
+  });
+
+  describe('cold start (getInitialURL)', () => {
+    it('adds a breadcrumb when app opened via deep link', async () => {
+      mockGetInitialURL.mockResolvedValue('myapp://profile/123?token=secret');
+
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      await Promise.resolve(); // flush microtasks
+
+      expect(mockAddBreadcrumb).toHaveBeenCalledWith(
+        expect.objectContaining({
+          category: 'deeplink',
+          type: 'navigation',
+        }),
+      );
+    });
+
+    it('strips query params and ID segments when sendDefaultPii is false', async () => {
+      mockGetInitialURL.mockResolvedValue('myapp://profile/123?token=secret');
+
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      await Promise.resolve();
+
+      expect(mockAddBreadcrumb).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'myapp://profile/<id>',
+          data: { url: 'myapp://profile/<id>' },
+        }),
+      );
+    });
+
+    it('keeps full URL when sendDefaultPii is true', async () => {
+      mockGetClient.mockReturnValue({
+        getOptions: () => ({ sendDefaultPii: true }),
+      });
+      mockGetInitialURL.mockResolvedValue('myapp://profile/123?token=secret');
+
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      await Promise.resolve();
+
+      expect(mockAddBreadcrumb).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'myapp://profile/123?token=secret',
+          data: { url: 'myapp://profile/123?token=secret' },
+        }),
+      );
+    });
+
+    it('does not add a breadcrumb when getInitialURL returns null', async () => {
+      mockGetInitialURL.mockResolvedValue(null);
+
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      await Promise.resolve();
+
+      expect(mockAddBreadcrumb).not.toHaveBeenCalled();
+    });
+
+    it('does not throw when getInitialURL rejects', async () => {
+      mockGetInitialURL.mockRejectedValue(new Error('Linking error'));
+
+      const integration = deeplinkIntegration();
+      expect(() =>
+        integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]),
+      ).not.toThrow();
+
+      await new Promise(resolve => setTimeout(resolve, 0));
+      expect(mockAddBreadcrumb).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('warm open (url event)', () => {
+    it('adds a breadcrumb when a url event is received', () => {
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      const handler = mockAddEventListener.mock.calls[0]?.[1];
+      handler?.({ url: 'myapp://notifications/456' });
+
+      expect(mockAddBreadcrumb).toHaveBeenCalledWith(
+        expect.objectContaining({
+          category: 'deeplink',
+          type: 'navigation',
+        }),
+      );
+    });
+
+    it('strips query params and ID segments on url event when sendDefaultPii is false', () => {
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      const handler = mockAddEventListener.mock.calls[0]?.[1];
+      handler?.({ url: 'myapp://notifications/456?ref=push' });
+
+      expect(mockAddBreadcrumb).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'myapp://notifications/<id>',
+          data: { url: 'myapp://notifications/<id>' },
+        }),
+      );
+    });
+
+    it('keeps full URL on url event when sendDefaultPii is true', () => {
+      mockGetClient.mockReturnValue({
+        getOptions: () => ({ sendDefaultPii: true }),
+      });
+
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      const handler = mockAddEventListener.mock.calls[0]?.[1];
+      handler?.({ url: 'myapp://notifications/456?ref=push' });
+
+      expect(mockAddBreadcrumb).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'myapp://notifications/456?ref=push',
+          data: { url: 'myapp://notifications/456?ref=push' },
+        }),
+      );
+    });
+
+    it('registers the url event listener on setup', () => {
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      expect(mockAddEventListener).toHaveBeenCalledWith('url', expect.any(Function));
+    });
+  });
+
+  describe('URL sanitization', () => {
+    it('does not alter non-ID path segments', async () => {
+      mockGetInitialURL.mockResolvedValue('myapp://settings/profile');
+
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      await Promise.resolve();
+
+      expect(mockAddBreadcrumb).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'myapp://settings/profile',
+        }),
+      );
+    });
+
+    it('replaces UUID-like segments', async () => {
+      mockGetInitialURL.mockResolvedValue('myapp://order/a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+
+      const integration = deeplinkIntegration();
+      integration.setup?.({} as Parameters<NonNullable<typeof integration.setup>>[0]);
+
+      await Promise.resolve();
+
+      const call = mockAddBreadcrumb.mock.calls[0]?.[0];
+      expect(call?.message).not.toContain('a1b2c3d4');
+    });
+  });
+});
