react-fathom 0.1.10 → 0.2.0

package/src/native/FathomWebView.test.tsx

@@ -0,0 +1,410 @@
+import React, { createRef, act } from 'react'
+
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { render } from '@testing-library/react'
+
+import { FathomWebView, type FathomWebViewRef } from './FathomWebView'
+
+// Store mock WebView instance for testing
+let mockWebViewInstance: {
+  injectJavaScript: ReturnType<typeof vi.fn>
+  onMessage?: (event: any) => void
+  onError?: (event: any) => void
+  source?: { html: string }
+  javaScriptEnabled?: boolean
+} | null = null
+
+// Mock react-native
+vi.mock('react-native', () => ({
+  StyleSheet: {
+    create: vi.fn((styles) => styles),
+  },
+  View: ({ children }: { children?: React.ReactNode }) => (
+    <div data-testid="rn-view">{children}</div>
+  ),
+}))
+
+// Mock react-native-webview
+vi.mock('react-native-webview', () => {
+  const MockWebView = React.forwardRef((props: any, ref: any) => {
+    const injectJavaScript = vi.fn()
+
+    // Store for testing
+    mockWebViewInstance = {
+      injectJavaScript,
+      onMessage: props.onMessage,
+      onError: props.onError,
+      source: props.source,
+      javaScriptEnabled: props.javaScriptEnabled,
+    }
+
+    // Expose injectJavaScript via ref
+    React.useImperativeHandle(ref, () => ({
+      injectJavaScript,
+    }))
+
+    return (
+      <div
+        data-testid="webview"
+        data-source={JSON.stringify(props.source)}
+        data-javascript-enabled={props.javaScriptEnabled}
+      />
+    )
+  })
+
+  return { WebView: MockWebView }
+})
+
+describe('FathomWebView', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockWebViewInstance = null
+  })
+
+  describe('rendering', () => {
+    it('should render a WebView', () => {
+      const { getByTestId } = render(<FathomWebView siteId="TEST_SITE" />)
+
+      expect(getByTestId('webview')).toBeDefined()
+    })
+
+    it('should include siteId in the HTML source', () => {
+      const { getByTestId } = render(
+        <FathomWebView siteId="MY_CUSTOM_SITE_ID" />,
+      )
+
+      const webview = getByTestId('webview')
+      const source = JSON.parse(webview.getAttribute('data-source') || '{}')
+
+      expect(source.html).toContain('data-site="MY_CUSTOM_SITE_ID"')
+    })
+
+    it('should use default scriptDomain', () => {
+      const { getByTestId } = render(<FathomWebView siteId="TEST_SITE" />)
+
+      const webview = getByTestId('webview')
+      const source = JSON.parse(webview.getAttribute('data-source') || '{}')
+
+      expect(source.html).toContain('cdn.usefathom.com/script.js')
+    })
+
+    it('should use custom scriptDomain when provided', () => {
+      const { getByTestId } = render(
+        <FathomWebView siteId="TEST_SITE" scriptDomain="custom.domain.com" />,
+      )
+
+      const webview = getByTestId('webview')
+      const source = JSON.parse(webview.getAttribute('data-source') || '{}')
+
+      expect(source.html).toContain('custom.domain.com/script.js')
+    })
+
+    it('should enable JavaScript', () => {
+      const { getByTestId } = render(<FathomWebView siteId="TEST_SITE" />)
+
+      const webview = getByTestId('webview')
+      expect(webview.getAttribute('data-javascript-enabled')).toBe('true')
+    })
+  })
+
+  describe('ref methods', () => {
+    it('should expose trackPageview method', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.trackPageview).toBeDefined()
+      expect(typeof ref.current?.trackPageview).toBe('function')
+    })
+
+    it('should expose trackEvent method', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.trackEvent).toBeDefined()
+      expect(typeof ref.current?.trackEvent).toBe('function')
+    })
+
+    it('should expose trackGoal method', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.trackGoal).toBeDefined()
+      expect(typeof ref.current?.trackGoal).toBe('function')
+    })
+
+    it('should expose blockTrackingForMe method', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.blockTrackingForMe).toBeDefined()
+      expect(typeof ref.current?.blockTrackingForMe).toBe('function')
+    })
+
+    it('should expose enableTrackingForMe method', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.enableTrackingForMe).toBeDefined()
+      expect(typeof ref.current?.enableTrackingForMe).toBe('function')
+    })
+
+    it('should expose isReady method', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.isReady).toBeDefined()
+      expect(typeof ref.current?.isReady).toBe('function')
+    })
+
+    it('should return false from isReady before ready message', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.isReady()).toBe(false)
+    })
+  })
+
+  describe('JavaScript injection', () => {
+    it('should inject trackPageview command', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      ref.current?.trackPageview({ url: '/test-page' })
+
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('trackPageview'),
+      )
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('/test-page'),
+      )
+    })
+
+    it('should inject trackEvent command', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      ref.current?.trackEvent('button-click', { _value: 100 })
+
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('trackEvent'),
+      )
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('button-click'),
+      )
+    })
+
+    it('should inject trackGoal command', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      ref.current?.trackGoal('PURCHASE', 2999)
+
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('trackGoal'),
+      )
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('PURCHASE'),
+      )
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('2999'),
+      )
+    })
+
+    it('should inject blockTrackingForMe command', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      ref.current?.blockTrackingForMe()
+
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('blockTrackingForMe'),
+      )
+    })
+
+    it('should inject enableTrackingForMe command', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      ref.current?.enableTrackingForMe()
+
+      expect(mockWebViewInstance?.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('enableTrackingForMe'),
+      )
+    })
+  })
+
+  describe('message handling', () => {
+    it('should call onReady when ready message is received', () => {
+      const onReady = vi.fn()
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" onReady={onReady} />)
+
+      // Simulate ready message from WebView (wrapped in act for state update)
+      act(() => {
+        mockWebViewInstance?.onMessage?.({
+          nativeEvent: { data: JSON.stringify({ type: 'ready' }) },
+        })
+      })
+
+      expect(onReady).toHaveBeenCalled()
+    })
+
+    it('should set isReady to true when ready message is received', () => {
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" />)
+
+      expect(ref.current?.isReady()).toBe(false)
+
+      // Simulate ready message from WebView (wrapped in act for state update)
+      act(() => {
+        mockWebViewInstance?.onMessage?.({
+          nativeEvent: { data: JSON.stringify({ type: 'ready' }) },
+        })
+      })
+
+      expect(ref.current?.isReady()).toBe(true)
+    })
+
+    it('should call onError when error message is received', () => {
+      const onError = vi.fn()
+
+      render(<FathomWebView siteId="TEST_SITE" onError={onError} />)
+
+      // Simulate error message from WebView
+      mockWebViewInstance?.onMessage?.({
+        nativeEvent: {
+          data: JSON.stringify({ type: 'error', message: 'Script failed to load' }),
+        },
+      })
+
+      expect(onError).toHaveBeenCalledWith('Script failed to load')
+    })
+
+    it('should handle malformed messages gracefully', () => {
+      const onError = vi.fn()
+
+      render(<FathomWebView siteId="TEST_SITE" onError={onError} />)
+
+      // Simulate malformed message
+      expect(() => {
+        mockWebViewInstance?.onMessage?.({
+          nativeEvent: { data: 'not valid json' },
+        })
+      }).not.toThrow()
+    })
+  })
+
+  describe('WebView error handling', () => {
+    it('should call onError when WebView has an error', () => {
+      const onError = vi.fn()
+
+      render(<FathomWebView siteId="TEST_SITE" onError={onError} />)
+
+      // Simulate WebView error
+      mockWebViewInstance?.onError?.({
+        nativeEvent: { description: 'Network error' },
+      })
+
+      expect(onError).toHaveBeenCalledWith('Network error')
+    })
+
+    it('should use default error message when description is missing', () => {
+      const onError = vi.fn()
+
+      render(<FathomWebView siteId="TEST_SITE" onError={onError} />)
+
+      // Simulate WebView error without description
+      mockWebViewInstance?.onError?.({
+        nativeEvent: {},
+      })
+
+      expect(onError).toHaveBeenCalledWith('WebView error')
+    })
+  })
+
+  describe('debug logging', () => {
+    it('should log when debug is enabled', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" debug={true} />)
+
+      ref.current?.trackPageview({ url: '/test' })
+
+      expect(consoleSpy).toHaveBeenCalled()
+      consoleSpy.mockRestore()
+    })
+
+    it('should not log when debug is disabled', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+      const ref = createRef<FathomWebViewRef>()
+
+      render(<FathomWebView ref={ref} siteId="TEST_SITE" debug={false} />)
+
+      ref.current?.trackPageview({ url: '/test' })
+
+      expect(consoleSpy).not.toHaveBeenCalled()
+      consoleSpy.mockRestore()
+    })
+  })
+
+  describe('loadOptions', () => {
+    it('should include data-honor-dnt attribute when honorDNT is set', () => {
+      const { getByTestId } = render(
+        <FathomWebView siteId="TEST_SITE" loadOptions={{ honorDNT: true }} />,
+      )
+
+      const webview = getByTestId('webview')
+      const source = JSON.parse(webview.getAttribute('data-source') || '{}')
+
+      expect(source.html).toContain('data-honor-dnt="true"')
+    })
+
+    it('should include data-auto attribute when auto is false', () => {
+      const { getByTestId } = render(
+        <FathomWebView siteId="TEST_SITE" loadOptions={{ auto: false }} />,
+      )
+
+      const webview = getByTestId('webview')
+      const source = JSON.parse(webview.getAttribute('data-source') || '{}')
+
+      expect(source.html).toContain('data-auto="false"')
+    })
+
+    it('should include data-canonical attribute when canonical is false', () => {
+      const { getByTestId } = render(
+        <FathomWebView siteId="TEST_SITE" loadOptions={{ canonical: false }} />,
+      )
+
+      const webview = getByTestId('webview')
+      const source = JSON.parse(webview.getAttribute('data-source') || '{}')
+
+      expect(source.html).toContain('data-canonical="false"')
+    })
+
+    it('should include data-spa attribute when spa mode is set', () => {
+      const { getByTestId } = render(
+        <FathomWebView siteId="TEST_SITE" loadOptions={{ spa: 'auto' }} />,
+      )
+
+      const webview = getByTestId('webview')
+      const source = JSON.parse(webview.getAttribute('data-source') || '{}')
+
+      expect(source.html).toContain('data-spa="auto"')
+    })
+  })
+})

package/src/native/FathomWebView.tsx

@@ -0,0 +1,297 @@
+import React, {
+  forwardRef,
+  useImperativeHandle,
+  useRef,
+  useState,
+  useCallback,
+} from 'react'
+import { StyleSheet, View } from 'react-native'
+import { WebView, type WebViewMessageEvent } from 'react-native-webview'
+
+import type { EventOptions, PageViewOptions, LoadOptions } from '../types'
+
+export interface FathomWebViewRef {
+  trackPageview: (opts?: PageViewOptions) => void
+  trackEvent: (eventName: string, opts?: EventOptions) => void
+  trackGoal: (code: string, cents: number) => void
+  blockTrackingForMe: () => void
+  enableTrackingForMe: () => void
+  isReady: () => boolean
+}
+
+export interface FathomWebViewProps {
+  /**
+   * Your Fathom Analytics site ID
+   */
+  siteId: string
+
+  /**
+   * Options passed to fathom.load()
+   */
+  loadOptions?: LoadOptions
+
+  /**
+   * Custom domain for Fathom script (if using custom domains feature)
+   * @default 'cdn.usefathom.com'
+   */
+  scriptDomain?: string
+
+  /**
+   * Called when the Fathom script has loaded and is ready
+   */
+  onReady?: () => void
+
+  /**
+   * Called when an error occurs loading the script
+   */
+  onError?: (error: string) => void
+
+  /**
+   * Enable debug logging
+   */
+  debug?: boolean
+}
+
+/**
+ * Hidden WebView component that loads and manages the Fathom Analytics script.
+ *
+ * This component renders an invisible WebView that loads the official Fathom
+ * tracking script, allowing React Native apps to use Fathom's full functionality.
+ *
+ * @example
+ * ```tsx
+ * const fathomRef = useRef<FathomWebViewRef>(null)
+ *
+ * <FathomWebView
+ *   ref={fathomRef}
+ *   siteId="ABCDEFGH"
+ *   onReady={() => console.log('Fathom ready!')}
+ * />
+ *
+ * // Later, track events:
+ * fathomRef.current?.trackPageview({ url: '/home' })
+ * ```
+ */
+export const FathomWebView = forwardRef<FathomWebViewRef, FathomWebViewProps>(
+  function FathomWebView(
+    {
+      siteId,
+      loadOptions = {},
+      scriptDomain = 'cdn.usefathom.com',
+      onReady,
+      onError,
+      debug = false,
+    },
+    ref,
+  ) {
+    const webViewRef = useRef<WebView>(null)
+    const [isReady, setIsReady] = useState(false)
+
+    const log = useCallback(
+      (...args: unknown[]) => {
+        if (debug) {
+          console.log('[react-fathom/webview]', ...args)
+        }
+      },
+      [debug],
+    )
+
+    // Build data attributes for load options
+    const buildDataAttributes = useCallback(() => {
+      const attrs: string[] = [`data-site="${siteId}"`]
+
+      if (loadOptions.auto === false) {
+        attrs.push('data-auto="false"')
+      }
+      if (loadOptions.honorDNT) {
+        attrs.push('data-honor-dnt="true"')
+      }
+      if (loadOptions.canonical === false) {
+        attrs.push('data-canonical="false"')
+      }
+      if (loadOptions.spa) {
+        attrs.push(`data-spa="${loadOptions.spa}"`)
+      }
+
+      return attrs.join(' ')
+    }, [siteId, loadOptions])
+
+    // HTML content that loads the Fathom script
+    const htmlContent = `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <script src="https://${scriptDomain}/script.js" ${buildDataAttributes()} defer></script>
+          <script>
+            // Wait for Fathom to be available
+            function waitForFathom(callback, maxAttempts = 50) {
+              let attempts = 0;
+              const check = () => {
+                attempts++;
+                if (typeof window.fathom !== 'undefined') {
+                  callback();
+                } else if (attempts < maxAttempts) {
+                  setTimeout(check, 100);
+                } else {
+                  window.ReactNativeWebView.postMessage(JSON.stringify({
+                    type: 'error',
+                    message: 'Fathom script failed to load after ' + (maxAttempts * 100) + 'ms'
+                  }));
+                }
+              };
+              check();
+            }
+
+            // Initialize when DOM is ready
+            document.addEventListener('DOMContentLoaded', () => {
+              waitForFathom(() => {
+                window.ReactNativeWebView.postMessage(JSON.stringify({
+                  type: 'ready'
+                }));
+              });
+            });
+
+            // Handle commands from React Native
+            window.handleCommand = function(command) {
+              if (typeof window.fathom === 'undefined') {
+                console.warn('Fathom not loaded yet');
+                return;
+              }
+
+              try {
+                switch (command.action) {
+                  case 'trackPageview':
+                    window.fathom.trackPageview(command.options || {});
+                    break;
+                  case 'trackEvent':
+                    window.fathom.trackEvent(command.eventName, command.options || {});
+                    break;
+                  case 'trackGoal':
+                    window.fathom.trackGoal(command.code, command.cents);
+                    break;
+                  case 'blockTrackingForMe':
+                    window.fathom.blockTrackingForMe();
+                    break;
+                  case 'enableTrackingForMe':
+                    window.fathom.enableTrackingForMe();
+                    break;
+                  default:
+                    console.warn('Unknown command:', command.action);
+                }
+              } catch (error) {
+                window.ReactNativeWebView.postMessage(JSON.stringify({
+                  type: 'error',
+                  message: error.message
+                }));
+              }
+            };
+          </script>
+        </head>
+        <body></body>
+      </html>
+    `
+
+    const injectCommand = useCallback(
+      (command: Record<string, unknown>) => {
+        if (!webViewRef.current) {
+          log('WebView not available')
+          return
+        }
+
+        const script = `window.handleCommand(${JSON.stringify(command)}); true;`
+        webViewRef.current.injectJavaScript(script)
+        log('Injected command:', command)
+      },
+      [log],
+    )
+
+    const handleMessage = useCallback(
+      (event: WebViewMessageEvent) => {
+        try {
+          const data = JSON.parse(event.nativeEvent.data)
+
+          switch (data.type) {
+            case 'ready':
+              log('Fathom script loaded and ready')
+              setIsReady(true)
+              onReady?.()
+              break
+            case 'error':
+              log('Error from WebView:', data.message)
+              onError?.(data.message)
+              break
+            default:
+              log('Unknown message type:', data.type)
+          }
+        } catch {
+          log('Failed to parse WebView message:', event.nativeEvent.data)
+        }
+      },
+      [log, onReady, onError],
+    )
+
+    // Expose methods via ref
+    useImperativeHandle(
+      ref,
+      () => ({
+        trackPageview: (opts?: PageViewOptions) => {
+          injectCommand({ action: 'trackPageview', options: opts })
+        },
+        trackEvent: (eventName: string, opts?: EventOptions) => {
+          injectCommand({ action: 'trackEvent', eventName, options: opts })
+        },
+        trackGoal: (code: string, cents: number) => {
+          injectCommand({ action: 'trackGoal', code, cents })
+        },
+        blockTrackingForMe: () => {
+          injectCommand({ action: 'blockTrackingForMe' })
+        },
+        enableTrackingForMe: () => {
+          injectCommand({ action: 'enableTrackingForMe' })
+        },
+        isReady: () => isReady,
+      }),
+      [injectCommand, isReady],
+    )
+
+    return (
+      <View style={styles.container}>
+        <WebView
+          ref={webViewRef}
+          source={{ html: htmlContent }}
+          onMessage={handleMessage}
+          onError={(syntheticEvent) => {
+            const { nativeEvent } = syntheticEvent
+            log('WebView error:', nativeEvent)
+            onError?.(nativeEvent.description || 'WebView error')
+          }}
+          javaScriptEnabled={true}
+          domStorageEnabled={true}
+          // Hide the WebView completely
+          style={styles.webview}
+          // Prevent any user interaction
+          scrollEnabled={false}
+          bounces={false}
+          // Optimize for background operation
+          cacheEnabled={true}
+          incognito={false}
+        />
+      </View>
+    )
+  },
+)
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    width: 0,
+    height: 0,
+    overflow: 'hidden',
+  },
+  webview: {
+    width: 1,
+    height: 1,
+    opacity: 0,
+  },
+})