react-fathom 0.1.11 → 0.2.0

package/src/native/react-native.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Minimal type declarations for react-native modules used by react-fathom/native.
+ * This allows the package to compile without requiring react-native as a dev dependency.
+ */
+declare module 'react-native' {
+  export type AppStateStatus = 'active' | 'background' | 'inactive'
+
+  export interface AppStateStatic {
+    currentState: AppStateStatus
+    addEventListener(
+      event: 'change',
+      handler: (state: AppStateStatus) => void,
+    ): { remove: () => void }
+  }
+
+  export const AppState: AppStateStatic
+
+  export interface ViewStyle {
+    position?: 'absolute' | 'relative'
+    width?: number | string
+    height?: number | string
+    overflow?: 'visible' | 'hidden' | 'scroll'
+    opacity?: number
+  }
+
+  export interface StyleSheetStatic {
+    create<T extends Record<string, ViewStyle>>(styles: T): T
+  }
+
+  export const StyleSheet: StyleSheetStatic
+
+  export interface ViewProps {
+    style?: ViewStyle
+    children?: React.ReactNode
+  }
+
+  export const View: React.FC<ViewProps>
+}
+
+declare module 'react-native-webview' {
+  import type { Ref, RefObject, Component } from 'react'
+
+  export interface WebViewMessageEvent {
+    nativeEvent: {
+      data: string
+    }
+  }
+
+  export interface WebViewErrorEvent {
+    nativeEvent: {
+      description?: string
+      code?: number
+      domain?: string
+      url?: string
+    }
+  }
+
+  export interface WebViewProps {
+    source?: { html: string; uri?: never } | { uri: string; html?: never }
+    onMessage?: (event: WebViewMessageEvent) => void
+    onError?: (event: WebViewErrorEvent) => void
+    javaScriptEnabled?: boolean
+    domStorageEnabled?: boolean
+    style?: Record<string, unknown>
+    scrollEnabled?: boolean
+    bounces?: boolean
+    cacheEnabled?: boolean
+    incognito?: boolean
+  }
+
+  export class WebView extends Component<WebViewProps> {
+    injectJavaScript(script: string): void
+  }
+}

package/src/native/types.ts

@@ -0,0 +1,145 @@
+import type { MutableRefObject } from 'react'
+import type { FathomClient, EventOptions, LoadOptions, PageViewOptions } from '../types'
+import type { WebViewFathomClient } from './createWebViewClient'
+
+/**
+ * Options for the NativeFathomProvider component
+ */
+export interface NativeFathomProviderProps {
+  /**
+   * Your Fathom Analytics site ID
+   */
+  siteId: string
+
+  /**
+   * Options passed to fathom.load() in the WebView
+   */
+  loadOptions?: LoadOptions
+
+  /**
+   * Custom domain for Fathom script (if using Fathom's custom domains feature)
+   * @default 'cdn.usefathom.com'
+   */
+  scriptDomain?: string
+
+  /**
+   * Default options merged into all trackPageview calls
+   */
+  defaultPageviewOptions?: PageViewOptions
+
+  /**
+   * Default options merged into all trackEvent calls
+   */
+  defaultEventOptions?: EventOptions
+
+  /**
+   * Enable automatic app state tracking (foreground/background)
+   * Tracks 'app-foreground' and 'app-background' events
+   * @default false
+   */
+  trackAppState?: boolean
+
+  /**
+   * Enable debug logging
+   * @default false
+   */
+  debug?: boolean
+
+  /**
+   * Called when the Fathom script has loaded and is ready
+   */
+  onReady?: () => void
+
+  /**
+   * Called when an error occurs loading the script
+   */
+  onError?: (error: string) => void
+
+  /**
+   * A ref that will be populated with the WebView-based Fathom client instance.
+   * This allows the parent component that composes the provider to access
+   * the client directly, since it cannot use useFathom() (context only flows
+   * downward to children).
+   *
+   * The client is a WebViewFathomClient which extends FathomClient with
+   * additional methods for queue management.
+   *
+   * @example
+   * ```tsx
+   * import { NativeFathomProvider, WebViewFathomClient } from 'react-fathom/native'
+   *
+   * function App() {
+   *   const clientRef = useRef<WebViewFathomClient>(null);
+   *
+   *   const handleDeepLink = (url: string) => {
+   *     clientRef.current?.trackEvent('deep_link', { _url: url });
+   *   };
+   *
+   *   return (
+   *     <NativeFathomProvider siteId="..." clientRef={clientRef}>
+   *       <YourApp />
+   *     </NativeFathomProvider>
+   *   );
+   * }
+   * ```
+   */
+  clientRef?: MutableRefObject<WebViewFathomClient | null>
+
+  /**
+   * Children to render
+   */
+  children: React.ReactNode
+}
+
+/**
+ * Options for the useNavigationTracking hook
+ */
+export interface UseNavigationTrackingOptions {
+  /**
+   * React Navigation navigation container ref
+   */
+  navigationRef: React.RefObject<any>
+
+  /**
+   * Transform the route name before tracking (e.g., add prefixes)
+   */
+  transformRouteName?: (routeName: string) => string
+
+  /**
+   * Filter which routes should be tracked (return false to skip)
+   */
+  shouldTrackRoute?: (routeName: string, params?: Record<string, any>) => boolean
+
+  /**
+   * Include route params in the tracked URL
+   */
+  includeParams?: boolean
+}
+
+/**
+ * Options for the useAppStateTracking hook
+ */
+export interface UseAppStateTrackingOptions {
+  /**
+   * Event name for when the app comes to foreground (default: 'app-foreground')
+   */
+  foregroundEventName?: string
+
+  /**
+   * Event name for when the app goes to background (default: 'app-background')
+   */
+  backgroundEventName?: string
+
+  /**
+   * Additional event options to include with app state events
+   */
+  eventOptions?: EventOptions
+
+  /**
+   * Callback when app state changes
+   */
+  onStateChange?: (state: 'active' | 'background' | 'inactive') => void
+}
+
+// Re-export core types for convenience
+export type { FathomClient, EventOptions, LoadOptions, PageViewOptions }

package/src/native/useAppStateTracking.test.ts

@@ -0,0 +1,249 @@
+import React from 'react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { renderHook, act } from '@testing-library/react'
+
+import { FathomProvider } from '../FathomProvider'
+import { useAppStateTracking } from './useAppStateTracking'
+
+// Store the listener callback for testing
+let appStateChangeCallback: ((state: string) => void) | null = null
+const mockRemove = vi.fn()
+
+// Mock react-native AppState
+vi.mock('react-native', () => ({
+  AppState: {
+    currentState: 'active',
+    addEventListener: vi.fn((event, callback) => {
+      if (event === 'change') {
+        appStateChangeCallback = callback
+      }
+      return { remove: mockRemove }
+    }),
+  },
+}))
+
+describe('useAppStateTracking', () => {
+  const mockTrackEvent = vi.fn()
+  const mockClient = {
+    trackEvent: mockTrackEvent,
+    trackPageview: vi.fn(),
+    trackGoal: vi.fn(),
+    load: vi.fn(),
+    setSite: vi.fn(),
+    blockTrackingForMe: vi.fn(),
+    enableTrackingForMe: vi.fn(),
+    isTrackingEnabled: vi.fn(() => true),
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    appStateChangeCallback = null
+  })
+
+  const createWrapper = () => {
+    return ({ children }: { children: React.ReactNode }) =>
+      React.createElement(FathomProvider, { client: mockClient }, children)
+  }
+
+  it('should set up AppState listener on mount', async () => {
+    const reactNative = await import('react-native')
+
+    renderHook(() => useAppStateTracking(), { wrapper: createWrapper() })
+
+    expect(reactNative.AppState.addEventListener).toHaveBeenCalledWith(
+      'change',
+      expect.any(Function),
+    )
+  })
+
+  it('should clean up listener on unmount', () => {
+    const { unmount } = renderHook(() => useAppStateTracking(), {
+      wrapper: createWrapper(),
+    })
+
+    unmount()
+
+    expect(mockRemove).toHaveBeenCalled()
+  })
+
+  it('should track foreground event when app becomes active', () => {
+    renderHook(() => useAppStateTracking(), { wrapper: createWrapper() })
+
+    // Simulate app going to background then foreground
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    act(() => {
+      appStateChangeCallback?.('active')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('app-foreground', expect.anything())
+  })
+
+  it('should track background event when app goes to background', () => {
+    renderHook(() => useAppStateTracking(), { wrapper: createWrapper() })
+
+    // Simulate app going to background (from active state)
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('app-background', expect.anything())
+  })
+
+  it('should use custom foreground event name', () => {
+    renderHook(
+      () =>
+        useAppStateTracking({
+          foregroundEventName: 'app-resumed',
+        }),
+      { wrapper: createWrapper() },
+    )
+
+    // Simulate app going to background then foreground
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    act(() => {
+      appStateChangeCallback?.('active')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('app-resumed', expect.anything())
+  })
+
+  it('should use custom background event name', () => {
+    renderHook(
+      () =>
+        useAppStateTracking({
+          backgroundEventName: 'app-paused',
+        }),
+      { wrapper: createWrapper() },
+    )
+
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('app-paused', expect.anything())
+  })
+
+  it('should include eventOptions in tracked events', () => {
+    const eventOptions = { _site_id: 'app-state-tracking' }
+
+    renderHook(
+      () =>
+        useAppStateTracking({
+          eventOptions,
+        }),
+      { wrapper: createWrapper() },
+    )
+
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('app-background', eventOptions)
+  })
+
+  it('should call onStateChange callback when state changes', () => {
+    const onStateChange = vi.fn()
+
+    renderHook(
+      () =>
+        useAppStateTracking({
+          onStateChange,
+        }),
+      { wrapper: createWrapper() },
+    )
+
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    expect(onStateChange).toHaveBeenCalledWith('background')
+  })
+
+  it('should track inactive state as background', () => {
+    renderHook(() => useAppStateTracking(), { wrapper: createWrapper() })
+
+    act(() => {
+      appStateChangeCallback?.('inactive')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('app-background', expect.anything())
+  })
+
+  it('should track foreground when transitioning from inactive to active', () => {
+    renderHook(() => useAppStateTracking(), { wrapper: createWrapper() })
+
+    // Go to inactive first
+    act(() => {
+      appStateChangeCallback?.('inactive')
+    })
+
+    mockTrackEvent.mockClear()
+
+    // Then to active
+    act(() => {
+      appStateChangeCallback?.('active')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('app-foreground', expect.anything())
+  })
+
+  it('should not track when transitioning between inactive and background', () => {
+    renderHook(() => useAppStateTracking(), { wrapper: createWrapper() })
+
+    // Go to inactive first
+    act(() => {
+      appStateChangeCallback?.('inactive')
+    })
+
+    mockTrackEvent.mockClear()
+
+    // Then to background (no foreground event should be tracked)
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    // Should not track foreground event
+    expect(mockTrackEvent).not.toHaveBeenCalledWith(
+      'app-foreground',
+      expect.anything(),
+    )
+  })
+
+  it('should work with all options combined', () => {
+    const onStateChange = vi.fn()
+    const eventOptions = { _value: 1 }
+
+    renderHook(
+      () =>
+        useAppStateTracking({
+          foregroundEventName: 'resumed',
+          backgroundEventName: 'paused',
+          eventOptions,
+          onStateChange,
+        }),
+      { wrapper: createWrapper() },
+    )
+
+    act(() => {
+      appStateChangeCallback?.('background')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('paused', eventOptions)
+    expect(onStateChange).toHaveBeenCalledWith('background')
+
+    act(() => {
+      appStateChangeCallback?.('active')
+    })
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('resumed', eventOptions)
+    expect(onStateChange).toHaveBeenCalledWith('active')
+  })
+})

package/src/native/useAppStateTracking.ts

@@ -0,0 +1,66 @@
+import { useEffect, useRef } from 'react'
+import { AppState, type AppStateStatus } from 'react-native'
+
+import { useFathom } from '../hooks/useFathom'
+import type { UseAppStateTrackingOptions } from './types'
+
+/**
+ * Hook that tracks app state changes (foreground/background) as Fathom events.
+ *
+ * This is useful for understanding user engagement patterns and session behavior.
+ *
+ * @example
+ * ```tsx
+ * import { useAppStateTracking } from 'react-fathom/native'
+ *
+ * function App() {
+ *   useAppStateTracking({
+ *     foregroundEventName: 'app-resumed',
+ *     backgroundEventName: 'app-paused',
+ *     onStateChange: (state) => {
+ *       console.log('App state:', state)
+ *     },
+ *   })
+ *
+ *   return <YourApp />
+ * }
+ * ```
+ */
+export function useAppStateTracking(options: UseAppStateTrackingOptions = {}) {
+  const {
+    foregroundEventName = 'app-foreground',
+    backgroundEventName = 'app-background',
+    eventOptions,
+    onStateChange,
+  } = options
+
+  const { trackEvent } = useFathom()
+  const appStateRef = useRef<AppStateStatus>(AppState.currentState)
+
+  useEffect(() => {
+    const handleAppStateChange = (nextAppState: AppStateStatus) => {
+      const previousState = appStateRef.current
+
+      // Track when app comes to foreground
+      if (previousState.match(/inactive|background/) && nextAppState === 'active') {
+        trackEvent?.(foregroundEventName, eventOptions)
+      }
+
+      // Track when app goes to background
+      if (previousState === 'active' && nextAppState.match(/inactive|background/)) {
+        trackEvent?.(backgroundEventName, eventOptions)
+      }
+
+      // Call the optional state change callback
+      onStateChange?.(nextAppState as 'active' | 'background' | 'inactive')
+
+      appStateRef.current = nextAppState
+    }
+
+    const subscription = AppState.addEventListener('change', handleAppStateChange)
+
+    return () => {
+      subscription.remove()
+    }
+  }, [trackEvent, foregroundEventName, backgroundEventName, eventOptions, onStateChange])
+}