Implement URL parameter ferrying across documentation site links

Author: cursoragent

URL_PARAMETER_FERRYING.md

@@ -0,0 +1,136 @@
+# URL Parameter Ferrying Implementation
+
+This document describes the URL parameter ferrying functionality that has been implemented in your Sentry documentation site.
+
+## Overview
+
+URL parameter ferrying automatically preserves and transfers specific URL parameters from the current page to all internal links on the site. This ensures that important tracking parameters (like UTM codes, promo codes, etc.) are maintained as users navigate through the documentation.
+
+## Implemented Features
+
+### 1. Updated Parameter Patterns
+
+The parameter syncing patterns in `src/utils.ts` have been updated to focus on:
+- `^utm_` - UTM tracking parameters (utm_source, utm_medium, utm_campaign, etc.)
+- `^promo_` - Promotional parameters (promo_code, promo_id, etc.)
+- `code` - Generic code parameters
+- `ref` - Referral parameters
+
+**Previous patterns:** `[/utm_/i, /promo_/i, /gclid/i, /original_referrer/i]`
+**Updated patterns:** `[/^utm_/i, /^promo_/i, /code/, /ref/]`
+
+### 2. Enhanced Utility Functions
+
+**`ferryUrlParams(targetUrl, additionalParams)`** - A new utility function that:
+- Takes a target URL and optional additional parameters
+- Extracts matching parameters from the current page
+- Appends them to the target URL
+- Returns the modified URL with parameters
+
+### 3. Updated Link Components
+
+**SmartLink Component** (`src/components/smartLink.tsx`):
+- Now automatically ferries parameters to internal links
+- External links remain unchanged
+- Preserves existing functionality while adding parameter ferrying
+
+**NavLink Component** (`src/components/navlink.tsx`):
+- Navigation links now automatically include ferried parameters
+- Maintains the existing Button styling and behavior
+
+### 4. Automatic Parameter Ferrying Component
+
+**ParamFerry Component** (`src/components/paramFerry.tsx`):
+- A client-side component that automatically processes all links on the page
+- Uses MutationObserver to handle dynamically added links
+- Skips external links, anchors, mailto, and tel links
+- Marks processed links to avoid duplicate processing
+
+**Added to Layout** (`app/layout.tsx`):
+- The ParamFerry component is included in the root layout
+- Works automatically across all pages without additional setup
+
+## How It Works
+
+1. **Page Load**: When a page loads with URL parameters matching the patterns, the ParamFerry component identifies them
+2. **Link Processing**: All internal links on the page are processed to include the relevant parameters
+3. **Dynamic Updates**: New links added to the page (via JavaScript) are automatically processed
+4. **Navigation**: When users click internal links, they carry forward the tracked parameters
+
+## Examples
+
+### Before Implementation
+```
+Current URL: /docs/platforms/javascript/?utm_source=google&utm_medium=cpc&code=SUMMER2024
+Link on page: /docs/error-reporting/
+User clicks: Goes to /docs/error-reporting/ (parameters lost)
+```
+
+### After Implementation
+```
+Current URL: /docs/platforms/javascript/?utm_source=google&utm_medium=cpc&code=SUMMER2024
+Link on page: /docs/error-reporting/ (automatically becomes /docs/error-reporting/?utm_source=google&utm_medium=cpc&code=SUMMER2024)
+User clicks: Goes to /docs/error-reporting/?utm_source=google&utm_medium=cpc&code=SUMMER2024 (parameters preserved)
+```
+
+## Usage in Components
+
+### Using the Enhanced SmartLink
+```tsx
+import {SmartLink} from 'sentry-docs/components/smartLink';
+
+// Parameters are automatically ferried
+<SmartLink href="/docs/getting-started/">Get Started</SmartLink>
+```
+
+### Using the ferryUrlParams Utility
+```tsx
+import {ferryUrlParams} from 'sentry-docs/utils';
+
+const linkUrl = ferryUrlParams('/docs/platforms/');
+// Returns URL with current page's tracked parameters appended
+```
+
+### Using NavLink
+```tsx
+import {NavLink} from 'sentry-docs/components/navlink';
+
+// Parameters are automatically ferried
+<NavLink href="/docs/guides/">Guides</NavLink>
+```
+
+## Browser Compatibility
+
+The implementation uses:
+- `URLSearchParams` for parameter handling
+- `MutationObserver` for dynamic link detection
+- Modern JavaScript features supported in all current browsers
+
+## Performance Considerations
+
+- Links are processed efficiently using native DOM methods
+- MutationObserver is used to minimize performance impact
+- Processed links are marked to avoid reprocessing
+- Debouncing prevents excessive processing during rapid DOM changes
+
+## Customization
+
+To modify the parameter patterns, update the `paramsToSync` array in `src/utils.ts`:
+
+```typescript
+const paramsToSync = [/^utm_/i, /^promo_/i, /code/, /ref/];
+```
+
+Add new patterns following the same format:
+- Use RegExp for pattern matching (e.g., `/^custom_/i`)
+- Use strings for exact matches (e.g., `'tracking_id'`)
+
+## Testing
+
+Test the functionality by:
+1. Loading a page with tracked parameters: `http://localhost:3000/docs/?utm_source=test&code=ABC123`
+2. Verifying that internal links include the parameters
+3. Clicking links to confirm parameters are preserved
+4. Checking that external links remain unchanged
+
+The implementation is now active across your entire documentation site and will automatically ferry the specified URL parameters between pages.

app/layout.tsx

@@ -7,6 +7,7 @@ import Script from 'next/script';
 import PlausibleProvider from 'next-plausible';
 
 import {ThemeProvider} from 'sentry-docs/components/theme-provider';
+import ParamFerry from 'sentry-docs/components/paramFerry';
 
 const rubik = Rubik({
   weight: ['400', '500', '700'],
@@ -44,6 +45,7 @@ export default function RootLayout({children}: {children: React.ReactNode}) {
         >
           <Theme accentColor="iris" grayColor="sand" radius="large" scaling="95%">
             {children}
+            <ParamFerry />
           </Theme>
         </ThemeProvider>
         <Script

src/components/navlink.tsx

@@ -1,12 +1,16 @@
 import {Button} from '@radix-ui/themes';
 import Link, {LinkProps as NextLinkProps} from 'next/link';
+import {ferryUrlParams} from 'sentry-docs/utils';
 
 export type NavLinkProps = React.PropsWithChildren<Omit<NextLinkProps, 'passHref'>> & {
   className?: string;
   style?: React.CSSProperties;
   target?: string;
 };
-export function NavLink({children, ...props}: NavLinkProps) {
+export function NavLink({children, href, ...props}: NavLinkProps) {
+  // Ferry URL parameters for navigation links
+  const ferriedHref = href ? ferryUrlParams(href.toString()) : href;
+
   return (
     <Button
       asChild
@@ -16,7 +20,7 @@ export function NavLink({children, ...props}: NavLinkProps) {
       radius="medium"
       className="font-medium text-[var(--foreground)] py-2 px-3 uppercase"
     >
-      <Link {...props}>{children}</Link>
+      <Link href={ferriedHref} {...props}>{children}</Link>
     </Button>
   );
 }

src/components/paramFerry.tsx

@@ -0,0 +1,131 @@
+'use client';
+
+import {useEffect} from 'react';
+
+/**
+ * ParamFerry component that automatically adds tracked URL parameters to all links on the page
+ * Focuses on utm_, promo_, code, and ref parameters
+ */
+export default function ParamFerry(): null {
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    // Define parameter patterns to ferry
+    const paramsToSync = [/^utm_/i, /^promo_/i, /code/, /ref/];
+
+    // Get current URL parameters
+    const getCurrentParams = () => {
+      const urlParams = new URLSearchParams(window.location.search);
+      const params: Record<string, string> = {};
+      
+      urlParams.forEach((value, key) => {
+        const shouldSync = paramsToSync.some(pattern => {
+          if (pattern instanceof RegExp) {
+            return pattern.test(key);
+          }
+          return key === pattern;
+        });
+        
+        if (shouldSync) {
+          params[key] = value;
+        }
+      });
+      
+      return params;
+    };
+
+    // Ferry parameters to a URL
+    const ferryParams = (targetUrl: string) => {
+      const params = getCurrentParams();
+      
+      if (Object.keys(params).length === 0) {
+        return targetUrl;
+      }
+
+      try {
+        const url = new URL(targetUrl, window.location.origin);
+        
+        // Add parameters to the URL
+        Object.entries(params).forEach(([key, value]) => {
+          if (value) {
+            url.searchParams.set(key, value);
+          }
+        });
+
+        return url.toString();
+      } catch (error) {
+        console.warn('Error ferrying parameters:', error);
+        return targetUrl;
+      }
+    };
+
+    const processLinks = () => {
+      // Get all anchor tags on the page
+      const links = document.querySelectorAll('a[href]');
+      
+      links.forEach(link => {
+        const anchor = link as HTMLAnchorElement;
+        const href = anchor.getAttribute('href');
+        if (!href) return;
+
+        // Skip if already processed
+        if (anchor.hasAttribute('data-param-ferried')) return;
+
+        // Skip external links, anchors, mailto, and tel links
+        if (
+          (href.startsWith('http') && !href.includes(window.location.hostname)) ||
+          href.startsWith('#') ||
+          href.startsWith('mailto:') ||
+          href.startsWith('tel:')
+        ) {
+          anchor.setAttribute('data-param-ferried', 'skip');
+          return;
+        }
+
+        try {
+          const ferriedUrl = ferryParams(href);
+          
+          if (ferriedUrl !== href) {
+            // For relative URLs, extract just the path and search params
+            if (!href.startsWith('http')) {
+              const url = new URL(ferriedUrl);
+              const newHref = url.pathname + url.search + url.hash;
+              anchor.setAttribute('href', newHref);
+            } else {
+              anchor.setAttribute('href', ferriedUrl);
+            }
+          }
+          
+          anchor.setAttribute('data-param-ferried', 'true');
+        } catch (error) {
+          console.warn('Error ferrying parameters for link:', href, error);
+          anchor.setAttribute('data-param-ferried', 'error');
+        }
+      });
+    };
+
+    // Process links immediately
+    processLinks();
+
+    // Set up a MutationObserver to handle dynamically added links
+    const observer = new MutationObserver(() => {
+      // Debounce to avoid excessive processing
+      setTimeout(processLinks, 10);
+    });
+
+    // Start observing
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+
+    // Cleanup
+    return () => {
+      observer.disconnect();
+    };
+  }, []);
+
+  return null;
+}

src/components/smartLink.tsx

@@ -4,6 +4,7 @@ import {useCallback} from 'react';
 import Link from 'next/link';
 
 import {ExternalLink} from './externalLink';
+import {ferryUrlParams} from 'sentry-docs/utils';
 
 interface Props {
   activeClassName?: string;
@@ -45,9 +46,12 @@ export function SmartLink({
     );
   }
 
+  // Ferry URL parameters for internal links
+  const ferriedUrl = ferryUrlParams(realTo);
+
   return (
     <Link
-      href={to || href || ''}
+      href={ferriedUrl}
       onClick={handleAutolinkClick}
       className={`${isActive ? activeClassName : ''} ${className}`}
       {...props}

src/utils.ts

@@ -74,7 +74,7 @@ type URLQueryObject = {
   [key: string]: string;
 };
 
-const paramsToSync = [/utm_/i, /promo_/i, /gclid/i, /original_referrer/i];
+const paramsToSync = [/^utm_/i, /^promo_/i, /code/, /ref/];
 
 export const marketingUrlParams = (): URLQueryObject => {
   const query = qs.parse(window.location.search);
@@ -91,6 +91,36 @@ export const marketingUrlParams = (): URLQueryObject => {
   return marketingParams;
 };
 
+/**
+ * Ferry URL parameters from current page to target URL
+ * @param targetUrl - The URL to append parameters to
+ * @param additionalParams - Optional additional parameters to include
+ * @returns URL with ferried parameters appended
+ */
+export const ferryUrlParams = (targetUrl: string, additionalParams: URLQueryObject = {}): string => {
+  if (typeof window === 'undefined') {
+    return targetUrl;
+  }
+
+  const currentParams = marketingUrlParams();
+  const allParams = {...currentParams, ...additionalParams};
+  
+  if (Object.keys(allParams).length === 0) {
+    return targetUrl;
+  }
+
+  const url = new URL(targetUrl, window.location.origin);
+  
+  // Add parameters to the URL
+  Object.entries(allParams).forEach(([key, value]) => {
+    if (value && typeof value === 'string') {
+      url.searchParams.set(key, value);
+    }
+  });
+
+  return url.toString();
+};
+
 export function captureException(exception: unknown): void {
   try {
     // Sentry may not be available, as we are using the Loader Script