e61b5ace-542a-4708-b4ff-2e866ef7d8e6

Committed 07 Jan 2026 08:52PM UTC coverage: 93.197% (-3.1%) from 96.266%

Build # e61b5ace-542a-4708-b4ff-2e866ef7d8e6

Build Type

push

circleci

Committed by

web-flow

Commit Message

Merge pull request #3 from ryanhefner/claude/improve-react-fathom-docs-Cve3K

[feat] React Native Client - Part 1

Run Details

175 of 193 branches covered (90.67%)

Branch coverage included in aggregate %.

224 of 243 new or added lines in 7 files covered. (92.18%)

373 of 395 relevant lines covered (94.43%)

16.48 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

88.12

/src/native/useNavigationTracking.ts

import { useEffect, useRef, useCallback } from 'react'

import { useFathom } from '../hooks/useFathom'
import type { UseNavigationTrackingOptions } from './types'

/**
 * Hook that tracks screen navigation as pageviews using React Navigation.
 *
 * This integrates with React Navigation's navigation container to automatically
 * track screen changes as Fathom pageviews.
 *
 * @example
 * ```tsx
 * import { NavigationContainer } from '@react-navigation/native'
 * import { useNavigationTracking } from 'react-fathom/native'
 *
 * function App() {
 *   const navigationRef = useNavigationContainerRef()
 *
 *   useNavigationTracking({
 *     navigationRef,
 *     transformRouteName: (name) => `/screens/${name}`,
 *   })
 *
 *   return (
 *     <NavigationContainer ref={navigationRef}>
 *       <Navigator />
 *     </NavigationContainer>
 *   )
 * }
 * ```
 */
export function useNavigationTracking(options: UseNavigationTrackingOptions) {
  const {
    navigationRef,
    transformRouteName,
    shouldTrackRoute,
    includeParams = false,
  } = options

  const { trackPageview } = useFathom()
  const routeNameRef = useRef<string | undefined>(undefined)

  /**
   * Get the current route name from the navigation state
   */
  const getCurrentRouteName = useCallback((): string | undefined => {
    if (!navigationRef.current) {
      return undefined
    }

    const state = navigationRef.current.getRootState?.()
    if (!state) {
      return undefined
    }

    // Navigate through nested navigators to get the deepest route
    let currentState = state
    while (currentState.routes[currentState.index]?.state) {
      currentState = currentState.routes[currentState.index].state as any
    }

    return currentState.routes[currentState.index]?.name
  }, [navigationRef])

  /**
   * Get the current route params from the navigation state
   */
  const getCurrentRouteParams = useCallback((): Record<string, any> | undefined => {
    if (!navigationRef.current) {
      return undefined
    }

    const state = navigationRef.current.getRootState?.()
    if (!state) {
      return undefined
    }

    // Navigate through nested navigators to get the deepest route
    let currentState = state
    while (currentState.routes[currentState.index]?.state) {
      currentState = currentState.routes[currentState.index].state as any
    }

    return currentState.routes[currentState.index]?.params as Record<string, any> | undefined
  }, [navigationRef])

  /**
   * Build the URL to track
   */
  const buildTrackingUrl = useCallback(
    (routeName: string, params?: Record<string, any>): string => {
      let url = transformRouteName ? transformRouteName(routeName) : `/${routeName}`

      if (includeParams && params && Object.keys(params).length > 0) {
        const queryString = Object.entries(params)
          .filter(([_, value]) => value !== undefined && value !== null)
          .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
          .join('&')

        if (queryString) {
          url += `?${queryString}`
        }
      }

      return url
    },
    [transformRouteName, includeParams],
  )

  /**
   * Handle navigation state change
   */
  const handleStateChange = useCallback(() => {
    const currentRouteName = getCurrentRouteName()
    const previousRouteName = routeNameRef.current

    if (currentRouteName && currentRouteName !== previousRouteName) {
      const params = includeParams ? getCurrentRouteParams() : undefined

      // Check if this route should be tracked
      if (shouldTrackRoute && !shouldTrackRoute(currentRouteName, params)) {
        routeNameRef.current = currentRouteName
        return
      }

      const url = buildTrackingUrl(currentRouteName, params)

      trackPageview?.({
        url,
        referrer: previousRouteName ? buildTrackingUrl(previousRouteName) : undefined,
      })

      routeNameRef.current = currentRouteName
    }
  }, [
    getCurrentRouteName,
    getCurrentRouteParams,
    shouldTrackRoute,
    buildTrackingUrl,
    trackPageview,
    includeParams,
  ])

  // Track initial route on mount
  useEffect(() => {
    // Small delay to ensure navigation is ready
    const timeout = setTimeout(() => {
      const initialRoute = getCurrentRouteName()
      if (initialRoute) {
        const params = includeParams ? getCurrentRouteParams() : undefined

        if (!shouldTrackRoute || shouldTrackRoute(initialRoute, params)) {
          const url = buildTrackingUrl(initialRoute, params)
          trackPageview?.({ url })
          routeNameRef.current = initialRoute
        }
      }
    }, 0)

    return () => clearTimeout(timeout)
  }, []) // Only on mount

  // Set up navigation state change listener
  useEffect(() => {
    if (!navigationRef.current) {
      return
    }

    // Listen for navigation state changes
    const unsubscribe = navigationRef.current.addListener?.('state', handleStateChange)

    return () => {
      unsubscribe?.()
    }
  }, [navigationRef, handleStateChange])
}

1	import { useEffect, useRef, useCallback } from 'react'
2
3	import { useFathom } from '../hooks/useFathom'
4	import type { UseNavigationTrackingOptions } from './types'
5
6	/**
7	* Hook that tracks screen navigation as pageviews using React Navigation.
8	*
9	* This integrates with React Navigation's navigation container to automatically
10	* track screen changes as Fathom pageviews.
11	*
12	* @example
13	* ```tsx
14	* import { NavigationContainer } from '@react-navigation/native'
15	* import { useNavigationTracking } from 'react-fathom/native'
16	*
17	* function App() {
18	* const navigationRef = useNavigationContainerRef()
19	*
20	* useNavigationTracking({
21	* navigationRef,
22	* transformRouteName: (name) => `/screens/${name}`,
23	* })
24	*
25	* return (
26	* <NavigationContainer ref={navigationRef}>
27	* <Navigator />
28	* </NavigationContainer>
29	* )
30	* }
31	* ```
32	*/
33	export function useNavigationTracking(options: UseNavigationTrackingOptions) {
34	const {
35	navigationRef,
36	transformRouteName,
37	shouldTrackRoute,
38	includeParams = false,	17✔
39	} = options	17✔
40
41	const { trackPageview } = useFathom()	17✔
42	const routeNameRef = useRef<string \| undefined>(undefined)	17✔
43
44	/**
45	* Get the current route name from the navigation state
46	*/
47	const getCurrentRouteName = useCallback((): string \| undefined => {	17✔
48	if (!navigationRef.current) {	19✔
49	return undefined	1✔
50	}
51
52	const state = navigationRef.current.getRootState?.()	18✔
53	if (!state) {	19✔
54	return undefined	1✔
55	}
56
57	// Navigate through nested navigators to get the deepest route
58	let currentState = state	17✔
59	while (currentState.routes[currentState.index]?.state) {	17✔
60	currentState = currentState.routes[currentState.index].state as any	2✔
61	}
62
63	return currentState.routes[currentState.index]?.name	17✔
64	}, [navigationRef])
65
66	/**
67	* Get the current route params from the navigation state
68	*/
69	const getCurrentRouteParams = useCallback((): Record<string, any> \| undefined => {	17✔
70	if (!navigationRef.current) {	6!
NEW 71	return undefined	×
72	}
73
74	const state = navigationRef.current.getRootState?.()	6✔
75	if (!state) {	6!
NEW 76	return undefined	×
77	}
78
79	// Navigate through nested navigators to get the deepest route
80	let currentState = state	6✔
81	while (currentState.routes[currentState.index]?.state) {	6✔
NEW 82	currentState = currentState.routes[currentState.index].state as any	×
83	}
84
85	return currentState.routes[currentState.index]?.params as Record<string, any> \| undefined	6✔
86	}, [navigationRef])
87
88	/**
89	* Build the URL to track
90	*/
91	const buildTrackingUrl = useCallback(	17✔
92	(routeName: string, params?: Record<string, any>): string => {
93	let url = transformRouteName ? transformRouteName(routeName) : `/${routeName}`	16✔
94
95	if (includeParams && params && Object.keys(params).length > 0) {	16✔
96	const queryString = Object.entries(params)	6✔
97	.filter(([_, value]) => value !== undefined && value !== null)	9✔
98	.map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)	7✔
99	.join('&')
100
101	if (queryString) {	6!
102	url += `?${queryString}`	6✔
103	}
104	}
105
106	return url	16✔
107	},
108	[transformRouteName, includeParams],
109	)
110
111	/**
112	* Handle navigation state change
113	*/
114	const handleStateChange = useCallback(() => {	17✔
115	const currentRouteName = getCurrentRouteName()	2✔
116	const previousRouteName = routeNameRef.current	2✔
117
118	if (currentRouteName && currentRouteName !== previousRouteName) {	2✔
119	const params = includeParams ? getCurrentRouteParams() : undefined	1!
120
121	// Check if this route should be tracked
122	if (shouldTrackRoute && !shouldTrackRoute(currentRouteName, params)) {	1!
NEW 123	routeNameRef.current = currentRouteName	×
NEW 124	return	×
125	}
126
127	const url = buildTrackingUrl(currentRouteName, params)	1✔
128
129	trackPageview?.({	1✔
130	url,
131	referrer: previousRouteName ? buildTrackingUrl(previousRouteName) : undefined,	1!
132	})
133
134	routeNameRef.current = currentRouteName	1✔
135	}
136	}, [
137	getCurrentRouteName,
138	getCurrentRouteParams,
139	shouldTrackRoute,
140	buildTrackingUrl,
141	trackPageview,
142	includeParams,
143	])
144
145	// Track initial route on mount
146	useEffect(() => {	17✔
147	// Small delay to ensure navigation is ready
148	const timeout = setTimeout(() => {	17✔
149	const initialRoute = getCurrentRouteName()	17✔
150	if (initialRoute) {	17✔
151	const params = includeParams ? getCurrentRouteParams() : undefined	15✔
152
153	if (!shouldTrackRoute \|\| shouldTrackRoute(initialRoute, params)) {	15✔
154	const url = buildTrackingUrl(initialRoute, params)	14✔
155	trackPageview?.({ url })	14✔
156	routeNameRef.current = initialRoute	14✔
157	}
158	}
159	}, 0)
160
161	return () => clearTimeout(timeout)	17✔
162	}, []) // Only on mount
163
164	// Set up navigation state change listener
165	useEffect(() => {	17✔
166	if (!navigationRef.current) {	17✔
167	return	1✔
168	}
169
170	// Listen for navigation state changes
171	const unsubscribe = navigationRef.current.addListener?.('state', handleStateChange)	16✔
172
173	return () => {	17✔
174	unsubscribe?.()	16✔
175	}
176	}, [navigationRef, handleStateChange])
177	}

ryanhefner / react-fathom / e61b5ace-542a-4708-b4ff-2e866ef7d8e6

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous