diff --git a/AGENTS.md b/AGENTS.md index bd2be7086..c6f6d252f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,7 +56,8 @@ GestureHandlerRootView └── ThemeProvider └── APIProvider └── AuthProvider - └── BottomSheetModalProvider + └── AnalyticsProvider + └── BottomSheetModalProvider ``` Never add a new provider outside `APIProvider` if it requires API access, or outside `AuthProvider` if it requires auth state. diff --git a/__tests__/components/providers/analytics-tracking.test.tsx b/__tests__/components/providers/analytics-tracking.test.tsx new file mode 100644 index 000000000..f1ea02243 --- /dev/null +++ b/__tests__/components/providers/analytics-tracking.test.tsx @@ -0,0 +1,217 @@ +import { useSegments } from 'expo-router'; + +import { AnalyticsProvider } from '@/components/providers/analytics'; +import { + useAnalyticsScreenTracking, + useAnalyticsSessionReset, +} from '@/components/providers/analytics-tracking'; +import { useAuth } from '@/components/providers/auth'; +import type { AnalyticsProviderAdapter } from '@/lib/analytics'; +import { clearUserIdentified, hasIdentifiedUser, markUserIdentified } from '@/lib/analytics'; +import { renderHook, waitFor } from '@/lib/test-utils'; + +jest.mock('expo-router', () => ({ + useSegments: jest.fn(), +})); + +jest.mock('@/components/providers/auth', () => ({ + useAuth: jest.fn(), +})); + +const mockUseSegments = useSegments as jest.MockedFunction<() => string[]>; +const mockUseAuth = useAuth as jest.MockedFunction; + +function mockAuthenticated(isAuthenticated: boolean) { + mockUseAuth.mockReturnValue({ + token: isAuthenticated ? 'token' : null, + isAuthenticated, + loading: false, + ready: true, + logout: jest.fn(), + }); +} + +function createMockProvider() { + return { + init: jest.fn(), + trackEvent: jest.fn(), + trackScreen: jest.fn(), + reset: jest.fn(), + } satisfies AnalyticsProviderAdapter; +} + +function renderWithAnalytics(hook: () => void, providers: ReadonlyArray) { + const wrapper = ({ children }: { children: React.ReactNode }) => ( + {children} + ); + return renderHook(hook, { wrapper }); +} + +describe('useAnalyticsScreenTracking', () => { + beforeEach(() => { + jest.clearAllMocks(); + }); + + it('tracks the current screen on mount', async () => { + const provider = createMockProvider(); + mockUseSegments.mockReturnValue(['sign-in']); + + renderWithAnalytics(useAnalyticsScreenTracking, [provider]); + + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledWith('/sign-in', undefined); + }); + expect(provider.trackScreen).toHaveBeenCalledTimes(1); + }); + + it('reports the route pattern, without route groups or dynamic values', async () => { + const provider = createMockProvider(); + mockUseSegments.mockReturnValue(['(app)', 'feed', '[id]']); + + renderWithAnalytics(useAnalyticsScreenTracking, [provider]); + + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledWith('/feed/[id]', undefined); + }); + }); + + it('reports the index route of a group as the root screen', async () => { + const provider = createMockProvider(); + mockUseSegments.mockReturnValue(['(app)']); + + renderWithAnalytics(useAnalyticsScreenTracking, [provider]); + + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledWith('/', undefined); + }); + }); + + it('tracks again when the route changes and not on unrelated re-renders', async () => { + const provider = createMockProvider(); + mockUseSegments.mockReturnValue(['(app)', 'feed']); + + const { rerender } = renderWithAnalytics(useAnalyticsScreenTracking, [provider]); + mockUseSegments.mockReturnValue(['(app)', 'feed']); + rerender({}); + + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledTimes(1); + }); + + mockUseSegments.mockReturnValue(['(app)', 'settings']); + rerender({}); + + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledTimes(2); + }); + expect(provider.trackScreen).toHaveBeenLastCalledWith('/settings', undefined); + }); + + it('reports only the redirect target when the route changes within the same tick', async () => { + const provider = createMockProvider(); + mockUseSegments.mockReturnValue(['(app)']); + + const { rerender } = renderWithAnalytics(useAnalyticsScreenTracking, [provider]); + mockUseSegments.mockReturnValue(['sign-in']); + rerender({}); + + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledWith('/sign-in', undefined); + }); + await new Promise(resolve => setImmediate(resolve)); + expect(provider.trackScreen).toHaveBeenCalledTimes(1); + }); + + it('does not report the same screen again when the providers array changes identity', async () => { + const provider = createMockProvider(); + mockUseSegments.mockReturnValue(['(app)', 'settings']); + const wrapper = ({ children }: { children: React.ReactNode }) => ( + {children} + ); + + const { rerender } = renderHook(useAnalyticsScreenTracking, { wrapper }); + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledTimes(1); + }); + + rerender({}); + rerender({}); + await new Promise(resolve => setImmediate(resolve)); + + expect(provider.trackScreen).toHaveBeenCalledTimes(1); + expect(provider.init).toHaveBeenCalledTimes(1); + }); +}); + +describe('useAnalyticsSessionReset', () => { + beforeEach(() => { + jest.clearAllMocks(); + clearUserIdentified(); + }); + + it('resets analytics when the user signs out', async () => { + const provider = createMockProvider(); + mockAuthenticated(true); + const { rerender } = renderWithAnalytics(useAnalyticsSessionReset, [provider]); + + mockAuthenticated(false); + rerender({}); + + await waitFor(() => { + expect(provider.reset).toHaveBeenCalledTimes(1); + }); + }); + + it('resets analytics when the app starts signed out after a user was identified', async () => { + const provider = createMockProvider(); + markUserIdentified(); + mockAuthenticated(false); + const { rerender } = renderWithAnalytics(useAnalyticsSessionReset, [provider]); + rerender({}); + + await waitFor(() => { + expect(provider.reset).toHaveBeenCalledTimes(1); + }); + expect(hasIdentifiedUser()).toBe(false); + }); + + it('does not reset when the app starts signed out and no user was identified', async () => { + const provider = createMockProvider(); + mockAuthenticated(false); + const { rerender } = renderWithAnalytics(useAnalyticsSessionReset, [provider]); + rerender({}); + + await waitFor(() => { + expect(provider.init).toHaveBeenCalledTimes(1); + }); + await new Promise(resolve => setImmediate(resolve)); + expect(provider.reset).not.toHaveBeenCalled(); + }); + + it('does not reset when the app starts signed in', async () => { + const provider = createMockProvider(); + mockAuthenticated(true); + const { rerender } = renderWithAnalytics(useAnalyticsSessionReset, [provider]); + rerender({}); + + await waitFor(() => { + expect(provider.init).toHaveBeenCalledTimes(1); + }); + expect(provider.reset).not.toHaveBeenCalled(); + }); + + it('does not reset when the user signs in', async () => { + const provider = createMockProvider(); + mockAuthenticated(false); + const { rerender } = renderWithAnalytics(useAnalyticsSessionReset, [provider]); + + mockAuthenticated(true); + rerender({}); + + await waitFor(() => { + expect(provider.init).toHaveBeenCalledTimes(1); + }); + await new Promise(resolve => setImmediate(resolve)); + expect(provider.reset).not.toHaveBeenCalled(); + }); +}); diff --git a/__tests__/components/providers/analytics.test.tsx b/__tests__/components/providers/analytics.test.tsx new file mode 100644 index 000000000..e5c386f88 --- /dev/null +++ b/__tests__/components/providers/analytics.test.tsx @@ -0,0 +1,339 @@ +import { + ANALYTICS_TIMEOUT_MS, + AnalyticsProvider, + useAnalytics, +} from '@/components/providers/analytics'; +import type { AnalyticsProviderAdapter } from '@/lib/analytics'; +import { clearUserIdentified, hasIdentifiedUser } from '@/lib/analytics'; +import { fireEvent, render, renderHook, screen, waitFor } from '@/lib/test-utils'; +import { Text, TouchableOpacity, View } from '@/components/ui'; + +function createMockProvider(overrides: Partial = {}) { + return { + init: jest.fn(), + trackEvent: jest.fn(), + trackScreen: jest.fn(), + identify: jest.fn(), + reset: jest.fn(), + ...overrides, + } satisfies AnalyticsProviderAdapter; +} + +function renderAnalytics(providers: ReadonlyArray) { + const wrapper = ({ children }: { children: React.ReactNode }) => ( + {children} + ); + return renderHook(() => useAnalytics(), { wrapper }); +} + +async function flushPromises() { + await new Promise(resolve => setImmediate(resolve)); +} + +describe('AnalyticsProvider', () => { + beforeEach(() => { + jest.spyOn(console, 'info').mockImplementation(() => undefined); + }); + + afterEach(() => { + jest.restoreAllMocks(); + }); + + it('initialises every provider once on mount', async () => { + const first = createMockProvider(); + const second = createMockProvider(); + + const { rerender } = renderAnalytics([first, second]); + rerender({}); + + await waitFor(() => { + expect(first.init).toHaveBeenCalledTimes(1); + expect(second.init).toHaveBeenCalledTimes(1); + }); + }); + + it('waits for init to finish before forwarding calls', async () => { + let finishInit!: () => void; + const provider = createMockProvider({ + init: jest.fn(async () => new Promise((resolve) => { + finishInit = resolve; + })), + }); + const { result } = renderAnalytics([provider]); + + result.current.trackScreen('/feed'); + await flushPromises(); + expect(provider.trackScreen).not.toHaveBeenCalled(); + + finishInit(); + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledWith('/feed', undefined); + }); + }); + + it('skips providers whose init failed without blocking the others', async () => { + const broken = createMockProvider({ + init: jest.fn(() => { + throw new Error('missing api key'); + }), + }); + const healthy = createMockProvider(); + const { result } = renderAnalytics([broken, healthy]); + + result.current.trackScreen('/feed'); + + await waitFor(() => { + expect(healthy.trackScreen).toHaveBeenCalledTimes(1); + }); + expect(broken.trackScreen).not.toHaveBeenCalled(); + expect(console.info).toHaveBeenCalledTimes(1); + }); + + it('gives up on a provider whose init never settles', async () => { + jest.useFakeTimers(); + try { + const hanging = createMockProvider({ init: jest.fn(async () => new Promise(() => undefined)) }); + const healthy = createMockProvider(); + const { result } = renderAnalytics([hanging, healthy]); + + result.current.trackScreen('/feed'); + await jest.advanceTimersByTimeAsync(ANALYTICS_TIMEOUT_MS); + + expect(healthy.trackScreen).toHaveBeenCalledTimes(1); + expect(hanging.trackScreen).not.toHaveBeenCalled(); + expect(console.info).toHaveBeenCalledTimes(1); + } + finally { + jest.useRealTimers(); + } + }); + + it('finishes a reset before forwarding later calls to the same provider', async () => { + const calls: string[] = []; + let finishReset!: () => void; + const provider = createMockProvider({ + reset: jest.fn(async () => new Promise((resolve) => { + finishReset = () => { + calls.push('reset'); + resolve(); + }; + })), + trackScreen: jest.fn(() => { + calls.push('trackScreen'); + }), + }); + const { result } = renderAnalytics([provider]); + + result.current.reset(); + result.current.trackScreen('/sign-in'); + + await waitFor(() => { + expect(provider.reset).toHaveBeenCalledTimes(1); + }); + await flushPromises(); + expect(provider.trackScreen).not.toHaveBeenCalled(); + + finishReset(); + await waitFor(() => { + expect(calls).toEqual(['reset', 'trackScreen']); + }); + }); + + it('does not hold later calls behind an event that never settles', async () => { + const provider = createMockProvider({ + trackEvent: jest.fn(async () => new Promise(() => undefined)), + }); + const { result } = renderAnalytics([provider]); + + result.current.trackEvent('BUTTON_PRESS', { accessibilityId: 'login-button' }); + result.current.trackScreen('/feed'); + result.current.reset(); + + await waitFor(() => { + expect(provider.trackScreen).toHaveBeenCalledWith('/feed', undefined); + expect(provider.reset).toHaveBeenCalledTimes(1); + }); + }); + + it('releases calls queued behind a reset that never settles after the timeout', async () => { + jest.useFakeTimers(); + try { + const provider = createMockProvider({ + reset: jest.fn(async () => new Promise(() => undefined)), + }); + const { result } = renderAnalytics([provider]); + + result.current.reset(); + result.current.trackScreen('/sign-in'); + await jest.advanceTimersByTimeAsync(0); + expect(provider.trackScreen).not.toHaveBeenCalled(); + + await jest.advanceTimersByTimeAsync(ANALYTICS_TIMEOUT_MS); + expect(provider.trackScreen).toHaveBeenCalledWith('/sign-in', undefined); + expect(console.info).toHaveBeenCalledTimes(1); + } + finally { + jest.useRealTimers(); + } + }); + + it('remembers whether a user was identified until reset', () => { + clearUserIdentified(); + const { result } = renderAnalytics([]); + + result.current.identify('user-1'); + expect(hasIdentifiedUser()).toBe(true); + + result.current.reset(); + expect(hasIdentifiedUser()).toBe(false); + }); + + it('does not log provider failures in production', async () => { + const globals = globalThis as unknown as { __DEV__: boolean }; + const previousDev = globals.__DEV__; + globals.__DEV__ = false; + try { + const failing = createMockProvider({ + trackScreen: jest.fn(() => { + throw new Error('failed for user-1'); + }), + }); + const { result } = renderAnalytics([failing]); + + result.current.trackScreen('/feed'); + + await waitFor(() => { + expect(failing.trackScreen).toHaveBeenCalledTimes(1); + }); + await flushPromises(); + expect(console.info).not.toHaveBeenCalled(); + } + finally { + globals.__DEV__ = previousDev; + } + }); + + it('fans out trackEvent to every provider', async () => { + const first = createMockProvider(); + const second = createMockProvider(); + const { result } = renderAnalytics([first, second]); + + result.current.trackEvent('BUTTON_PRESS', { accessibilityId: 'login-button' }); + + await waitFor(() => { + expect(first.trackEvent).toHaveBeenCalledWith('BUTTON_PRESS', { + accessibilityId: 'login-button', + }); + expect(second.trackEvent).toHaveBeenCalledWith('BUTTON_PRESS', { + accessibilityId: 'login-button', + }); + }); + }); + + it('fans out trackScreen to every provider', async () => { + const first = createMockProvider(); + const second = createMockProvider(); + const { result } = renderAnalytics([first, second]); + + result.current.trackScreen('/feed', { tab: 'home' }); + + await waitFor(() => { + expect(first.trackScreen).toHaveBeenCalledWith('/feed', { tab: 'home' }); + expect(second.trackScreen).toHaveBeenCalledWith('/feed', { tab: 'home' }); + }); + }); + + it('fans out identify and reset, skipping providers that do not implement them', async () => { + const full = createMockProvider(); + const minimal = createMockProvider({ identify: undefined, reset: undefined }); + const { result } = renderAnalytics([full, minimal]); + + result.current.identify('user-1', { plan: 'free' }); + result.current.reset(); + + await waitFor(() => { + expect(full.identify).toHaveBeenCalledWith('user-1', { plan: 'free' }); + expect(full.reset).toHaveBeenCalledTimes(1); + }); + await flushPromises(); + expect(console.info).not.toHaveBeenCalled(); + }); + + it('isolates provider failures so the other providers still receive the call', async () => { + const failing = createMockProvider({ + trackEvent: jest.fn(() => { + throw new Error('vendor is down'); + }), + }); + const rejecting = createMockProvider({ + trackScreen: jest.fn().mockRejectedValue(new Error('network')), + }); + const healthy = createMockProvider(); + const { result } = renderAnalytics([failing, rejecting, healthy]); + + expect(() => { + result.current.trackEvent('BUTTON_PRESS', { accessibilityId: 'login-button' }); + result.current.trackScreen('/feed'); + }).not.toThrow(); + + await waitFor(() => { + expect(healthy.trackEvent).toHaveBeenCalledTimes(1); + expect(healthy.trackScreen).toHaveBeenCalledTimes(1); + expect(console.info).toHaveBeenCalledTimes(2); + }); + }); + + it('rejects events that are not in the catalogue at compile time', async () => { + const provider = createMockProvider(); + const { result } = renderAnalytics([provider]); + + // @ts-expect-error unknown event names are not allowed + result.current.trackEvent('NOT_IN_CATALOGUE', {}); + // @ts-expect-error params must match the catalogue entry + result.current.trackEvent('BUTTON_PRESS', { wrong: true }); + + await waitFor(() => { + expect(provider.trackEvent).toHaveBeenCalledTimes(2); + }); + }); + + it('throws when useAnalytics is used outside of AnalyticsProvider', () => { + expect(() => renderHook(() => useAnalytics())).toThrow( + 'useAnalytics must be used within an AnalyticsProvider', + ); + }); +}); + +describe('useAnalytics in a component', () => { + it('tracks an event when the user presses a button', async () => { + const provider = createMockProvider(); + + const TestComponent = () => { + const analytics = useAnalytics(); + return ( + + analytics.trackEvent('BUTTON_PRESS', { accessibilityId: 'track-button' })} + > + Track + + + ); + }; + + render( + + + , + ); + + fireEvent.press(screen.getByTestId('track-button')); + + await waitFor(() => { + expect(provider.trackEvent).toHaveBeenCalledWith('BUTTON_PRESS', { + accessibilityId: 'track-button', + }); + }); + }); +}); diff --git a/__tests__/lib/analytics/console-provider.test.ts b/__tests__/lib/analytics/console-provider.test.ts new file mode 100644 index 000000000..7bdaed808 --- /dev/null +++ b/__tests__/lib/analytics/console-provider.test.ts @@ -0,0 +1,46 @@ +import { consoleAnalyticsProvider } from '@/lib/analytics'; + +const devGlobal = globalThis as unknown as { __DEV__: boolean }; + +describe('consoleAnalyticsProvider', () => { + let infoSpy: jest.SpyInstance; + const originalDev = devGlobal.__DEV__; + + beforeEach(() => { + infoSpy = jest.spyOn(console, 'info').mockImplementation(() => undefined); + }); + + afterEach(() => { + devGlobal.__DEV__ = originalDev; + infoSpy.mockRestore(); + }); + + it('logs every call in development builds', () => { + devGlobal.__DEV__ = true; + + consoleAnalyticsProvider.init(); + consoleAnalyticsProvider.trackEvent('BUTTON_PRESS', { accessibilityId: 'login-button' }); + consoleAnalyticsProvider.trackScreen('/feed'); + consoleAnalyticsProvider.identify?.('user-1', { plan: 'free' }); + consoleAnalyticsProvider.reset?.(); + + expect(infoSpy).toHaveBeenCalledTimes(5); + expect(infoSpy).toHaveBeenNthCalledWith(1, '[analytics]', 'init'); + expect(infoSpy).toHaveBeenNthCalledWith(2, '[analytics]', 'event: BUTTON_PRESS', { + accessibilityId: 'login-button', + }); + expect(infoSpy).toHaveBeenNthCalledWith(3, '[analytics]', 'screen: /feed'); + expect(infoSpy).toHaveBeenNthCalledWith(4, '[analytics]', 'identify: user-1', { plan: 'free' }); + expect(infoSpy).toHaveBeenNthCalledWith(5, '[analytics]', 'reset'); + }); + + it('is a no-op outside development builds', () => { + devGlobal.__DEV__ = false; + + consoleAnalyticsProvider.init(); + consoleAnalyticsProvider.trackEvent('BUTTON_PRESS', { accessibilityId: 'login-button' }); + consoleAnalyticsProvider.trackScreen('/feed'); + + expect(infoSpy).not.toHaveBeenCalled(); + }); +}); diff --git a/agent_docs/architecture.md b/agent_docs/architecture.md index c8f910d72..f6c14e204 100644 --- a/agent_docs/architecture.md +++ b/agent_docs/architecture.md @@ -62,6 +62,8 @@ Route guards are centralised in `src/app/_layout.tsx`. The `GuardedStack` compon | Translation strings | `src/translations/en.json` | | Environment config | `src/lib/env.js` (access via `Env` from `@/lib/env`) | | General persistent storage | `src/lib/storage.tsx` (MMKV) | +| Analytics — event catalogue & provider contract | `src/lib/analytics/types.ts` | +| Analytics — context, `useAnalytics()`, screen tracking, reset on sign out | `src/components/providers/analytics.tsx`, `src/components/providers/analytics-tracking.ts` | | Global TypeScript types | `src/types/index.ts` | --- diff --git a/cli/setup-project.js b/cli/setup-project.js index e9aa2e5c4..e577f3eae 100755 --- a/cli/setup-project.js +++ b/cli/setup-project.js @@ -153,7 +153,7 @@ const updateGitHubWorkflows = (projectName) => { }, { searchValue: - /^[ \t]*environment:[ \t]*\n[ \t]*name:[ \t]*template[ \t]*\n[ \t]*url:[ \t]*\S.*\n/m, + /^[ \t]*environment:[ \t]*\r?\n[ \t]*name:[ \t]*template[ \t]*\r?\n[ \t]*url:[ \t]*\S[^\r\n]*\r?\n/m, replaceValue: '', }, ], diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 9f5eb3040..bcde9bde0 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -142,6 +142,11 @@ export default defineConfig({ label: 'Storage', link: '/guides/storage/', }, + { + label: 'Analytics', + link: '/guides/analytics/', + badge: 'new', + }, { label: 'Upgrade Dependencies', link: '/guides/upgrading-deps/', diff --git a/docs/src/content/docs/guides/analytics.mdx b/docs/src/content/docs/guides/analytics.mdx new file mode 100644 index 000000000..2d22150db --- /dev/null +++ b/docs/src/content/docs/guides/analytics.mdx @@ -0,0 +1,181 @@ +--- +title: Analytics +description: Provider-agnostic analytics layer with typed events and automatic screen tracking. +head: + - tag: title + content: Analytics | React Native / Expo Starter +--- + +import CodeBlock from '../../../components/code.astro'; + +Analytics should be part of a project from day one, but the vendor is often chosen (or changed) later. The starter ships a small analytics layer that keeps vendor SDKs out of your screens and components: app code only ever calls `useAnalytics()`, and the layer fans every call out to the providers you register. + +Out of the box the layer is wired with a console provider, so it works with no vendor SDK and no native configuration. Swapping or adding a vendor is a change in a single file. + +## How it works + +``` +Screens / components + │ useAnalytics().trackEvent(...) / trackScreen(...) + ▼ +AnalyticsProvider (React context) ──► provider A (console) + ▲ ──► provider B (Firebase, Segment, ...) + │ +useAnalyticsScreenTracking (listens to expo-router route changes) +``` + +| Piece | Location | +| -------------------------------------------- | ----------------------------------------------- | +| Event catalogue and provider adapter contract | `src/lib/analytics/types.ts` | +| Built-in console provider | `src/lib/analytics/console-provider.ts` | +| React context, `useAnalytics()` hook | `src/components/providers/analytics.tsx` | +| Automatic screen tracking, reset on sign out | `src/components/providers/analytics-tracking.ts` | +| Wiring (which providers the app uses) | `src/app/_layout.tsx` | + +## Tracking events + +Use the `useAnalytics()` hook anywhere below the provider tree. `trackEvent` is typed against the event catalogue, so an unknown event name or a wrong params shape fails to compile. + +```tsx +import { useAnalytics } from '@/components/providers/analytics'; + +export function MyComponent() { + const analytics = useAnalytics(); + + const onPressButton = () => { + analytics.trackEvent('BUTTON_PRESS', { accessibilityId: 'submit-button' }); + }; + + return