[LC-1534]: Modular Product Analytics by Custard7 · Pull Request #948 · learningeconomy/LearnCard

Custard7 · 2026-01-22T19:48:30Z

Overview

🎟 Relevant Jira Issues

Fixes: LC-1534

📚 What is the context and goal of this PR?

This PR introduces a provider-agnostic analytics abstraction layer for learn-card-app. The goal is to decouple event tracking from specific analytics backends (Firebase), enabling us to:

Switch analytics providers via environment variables without code changes
Add PostHog as an alternative/replacement analytics provider
Create a centralized, type-safe event catalog
Lazy-load provider SDKs for bundle optimization

🥴 TL;DR:

New @analytics module with pluggable providers (Firebase, PostHog, Noop). All existing useFirebaseAnalytics calls migrated to useAnalytics with typed events. Set VITE_ANALYTICS_PROVIDER=posthog to switch providers.

💡 Feature Breakdown

New Analytics Module (src/analytics/)

File	Purpose
events.ts	Centralized event catalog with 11 typed events
`types.ts`	`AnalyticsProvider` interface definition
`providers/noop.ts`	No-op provider for dev/testing
`providers/posthog.ts`	PostHog provider with lazy SDK loading
providers/firebase.ts	Firebase provider (wraps existing implementation)
`context.tsx`	React context + `useAnalytics()` hook
`useSetAnalyticsUserId.ts`	Hook to identify users across providers
index.ts	Barrel exports for `@analytics` alias

Usage:

import { useAnalytics, AnalyticsEvents } from '@analytics';

const { track } = useAnalytics();
track(AnalyticsEvents.CLAIM_BOOST, { method: 'Dashboard', category: 'achievement' });

Configuration:

VITE_ANALYTICS_PROVIDER=posthog   # "posthog" | "firebase" | "noop"
VITE_POSTHOG_KEY=phc_xxx          # Required for PostHog
VITE_POSTHOG_HOST=https://...     # Optional

🛠 Important tradeoffs made:

Provider SDK is lazy-loaded on first use (not at app init) to minimize bundle impact
Firebase provider wraps existing useFirebaseAnalytics rather than rewriting to maintain compatibility
Events are queued during provider initialization to prevent data loss

🔍 Types of Changes

New feature (non-breaking change which adds functionality)

💳 Does This Create Any New Technical Debt?

No

Testing

🔬 How Can Someone QA This?

Test Firebase provider (default behavior):
- Build app without VITE_ANALYTICS_PROVIDER set
- Verify events appear in Firebase Analytics (existing behavior preserved)
Test PostHog provider:
- Set VITE_ANALYTICS_PROVIDER=posthog and add VITE_POSTHOG_KEY
- Claim a boost → verify claim_boost event in PostHog dashboard
- Create a boost → verify boostCMS_publish event
Test Noop provider:
- Set VITE_ANALYTICS_PROVIDER=noop
- Verify no errors, no tracking calls made
Test user identification:
- Log in → verify user ID is linked to events in analytics dashboard

📱 🖥 Which devices would you like help testing on?

iOS Simulator / Android Simulator / Chromium

🧪 Code Coverage

No new tests added - this is a refactor of existing analytics calls with new provider support. Manual QA via analytics dashboards.

Documentation

📝 Documentation Checklist

Internal/AI Docs

Code comments/JSDoc — Provider interface and event types are self-documenting

💭 Documentation Notes

Internal refactor with new provider support. Configuration is via standard env vars documented in ticket.

✅ PR Checklist

Related to a Jira issue (LC-1534)
My code follows style guidelines (eslint / prettier)
I have manually tested common end-2-end cases
I have reviewed my code
I have commented my code, particularly where ambiguous
New and existing unit tests pass locally with my changes
I have completed the Documentation Checklist above (or explained why N/A)
I have considered product analytics for user-facing features (use @analytics in learn-card-app)

🚀 Ready to squash-and-merge?:

Code is backwards compatible
There is not a "Do Not Merge" label on this PR
I have thoughtfully considered the security implications of this change.
This change does not expose new public facing endpoints that do not have authentication

changeset-bot · 2026-01-22T19:48:34Z

⚠️ No Changeset found

Latest commit: 1ffb58d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

netlify · 2026-01-22T19:48:35Z

✅ Deploy Preview for learncarddocs canceled.

Name	Link
🔨 Latest commit	`1ffb58d`
🔍 Latest deploy log	https://app.netlify.com/projects/learncarddocs/deploys/69727f11ae43800007a146b5

netlify · 2026-01-22T19:48:35Z

✅ Deploy Preview for staging-learncardapp ready!

Name	Link
🔨 Latest commit	`1ffb58d`
🔍 Latest deploy log	https://app.netlify.com/projects/staging-learncardapp/deploys/69727f11e76fa8000863e7bc
😎 Deploy Preview	https://deploy-preview-948--staging-learncardapp.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2026-01-22T19:48:47Z

👋 Hey there! It looks like you modified code, but didn't update the documentation in /docs.

If this PR introduces new features, changes APIs, or modifies behavior that users or developers need to know about, please consider updating the docs.

🏄 Windsurf Tip

You can ask Windsurf to help:

"Analyze the changes in this PR and update the gitbook docs in /docs accordingly."

Windsurf will review your changes and suggest appropriate documentation updates based on what was modified.

📚 Documentation Guide

Change Type	Doc Location
New feature/API	`docs/tutorials/` or `docs/how-to-guides/`
SDK/API changes	`docs/sdks/`
New concepts	`docs/core-concepts/`
App UI/UX flows	`docs/apps/` (LearnCard App, ScoutPass)
Internal patterns	`CLAUDE.md`

This is an automated reminder. If no docs are needed, feel free to ignore this message.

gitstream-cm

✨ PR Review

The PR introduces a well-structured analytics abstraction layer with provider-agnostic tracking. However, there are critical issues with event loss during initialization, type safety violations in the Firebase provider, and performance problems from unstable dependencies causing infinite effect re-runs.

3 issues detected:

🚀 Performance - Non-memoized function dependencies cause infinite effect re-execution 🛠️

Details: The useEffect has dependencies on getDID and identify functions. The getDID function from useWallet() is not memoized and creates a new reference on every render, causing this effect to re-run constantly. This leads to redundant identify() calls and unnecessary performance overhead.
File: apps/learn-card-app/src/analytics/useSetAnalyticsUserId.ts (44-44)
_{🛠️ A suggested code correction is included in the review comments.}

🐞 Bug - Unsafe type cast forces null through string-typed API that may not accept it 🛠️

Details: The reset() function uses a dangerous type cast null as unknown as string to bypass TypeScript's type checking when calling setUserId. This could cause runtime failures if Firebase Analytics doesn't properly handle null values, and indicates the API is being used incorrectly.
File: apps/learn-card-app/src/analytics/providers/firebase.ts (54-54)
_{🛠️ A suggested code correction is included in the review comments.}

🐞 Bug - Analytics events fired before async provider initialization are lost in production

Details: The provider initializes as NoopProvider and asynchronously loads the real provider. Between mount and provider initialization completing, any analytics calls (track, identify, etc.) are sent to NoopProvider which only logs in dev mode, causing production events to be lost. Critical startup events like user identification or first page views may never be tracked.
File: apps/learn-card-app/src/analytics/context.tsx

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.

💡 Tip: You can customize your AI Review using Guidelines Learn how}

gitstream-cm · 2026-01-22T19:51:34Z

+        if (currentUser) {
+            setUserId();
+        }
+    }, [currentUser, currentLCNUser, getDID, identify, options.debug]);


🚀 Performance - Infinite Effect Loop: Remove getDID and identify from the dependency array, or ensure useWallet() memoizes the getDID function with useCallback. The effect should primarily depend on currentUser changes, and the functions can be safely used without being dependencies since they're stable across the hook's lifecycle.

Suggested change

}, [currentUser, currentLCNUser, getDID, identify, options.debug]);

}, [currentUser, currentLCNUser, options.debug]);

Is this review accurate? Use 👍 or 👎 to rate it

If you want to tell us more, use /gs feedback e.g. /gs feedback this review doesn't make sense, I disagree, and it keeps repeating over and over

gitstream-cm · 2026-01-22T19:51:34Z

+
+    async reset(): Promise<void> {
+        try {
+            await FirebaseAnalytics.setUserId({ userId: null as unknown as string });


🐞 Bug - Type Safety Violation: Use an empty string '' instead of null, or check the Firebase Analytics documentation for the proper way to clear/reset the user ID. If null is genuinely required, add error handling and documentation explaining why this unsafe cast is necessary.

Suggested change

await FirebaseAnalytics.setUserId({ userId: null as unknown as string });

await FirebaseAnalytics.setUserId({ userId: '' });

Is this review accurate? Use 👍 or 👎 to rate it

If you want to tell us more, use /gs feedback e.g. /gs feedback this review doesn't make sense, I disagree, and it keeps repeating over and over

goblincore · 2026-02-20T16:33:43Z

@Custard7 We can close this PR now that #1018 is up - it is based off this branch, just adds to it - seems like you got most of it done so I just added the remaining items from the JIRA and tested Posthog.

Jacksón Smith added 4 commits January 21, 2026 17:49

Add useAnalytics and providers

cbf9bdb

Use @analytics alias

5798ccd

Migrate remaining analytic events

3070fd3

Add product analytic to pr template

1ffb58d

Custard7 temporarily deployed to ci-tests January 22, 2026 19:48 — with GitHub Actions Inactive

Custard7 changed the title ~~[LC-1534]: Product Analytics~~ [LC-1534]: Modular Product Analytics Jan 22, 2026

Custard7 marked this pull request as draft January 22, 2026 19:48

gitstream-cm Bot added the 30 min review label Jan 22, 2026

gitstream-cm Bot reviewed Jan 22, 2026

View reviewed changes

Custard7 closed this Feb 20, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[LC-1534]: Modular Product Analytics#948

[LC-1534]: Modular Product Analytics#948
Custard7 wants to merge 4 commits intomainfrom
lc-1534

Custard7 commented Jan 22, 2026 •

edited by atlassian Bot

Loading

Uh oh!

changeset-bot Bot commented Jan 22, 2026

Uh oh!

netlify Bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jan 22, 2026

Uh oh!

gitstream-cm Bot left a comment

Uh oh!

gitstream-cm Bot Jan 22, 2026

Uh oh!

gitstream-cm Bot Jan 22, 2026

Uh oh!

goblincore commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	}, [currentUser, currentLCNUser, getDID, identify, options.debug]);
	}, [currentUser, currentLCNUser, options.debug]);

	await FirebaseAnalytics.setUserId({ userId: null as unknown as string });
	await FirebaseAnalytics.setUserId({ userId: '' });

Conversation

Custard7 commented Jan 22, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

🎟 Relevant Jira Issues

📚 What is the context and goal of this PR?

🥴 TL;DR:

💡 Feature Breakdown

🛠 Important tradeoffs made:

🔍 Types of Changes

💳 Does This Create Any New Technical Debt?

Testing

🔬 How Can Someone QA This?

📱 🖥 Which devices would you like help testing on?

🧪 Code Coverage

Documentation

📝 Documentation Checklist

💭 Documentation Notes

✅ PR Checklist

🚀 Ready to squash-and-merge?:

Uh oh!

changeset-bot Bot commented Jan 22, 2026

⚠️ No Changeset found

Uh oh!

netlify Bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for learncarddocs canceled.

Uh oh!

netlify Bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for staging-learncardapp ready!

Uh oh!

github-actions Bot commented Jan 22, 2026

🏄 Windsurf Tip

Uh oh!

gitstream-cm Bot left a comment

Choose a reason for hiding this comment

✨ PR Review

Uh oh!

gitstream-cm Bot Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

gitstream-cm Bot Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

goblincore commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Custard7 commented Jan 22, 2026 •

edited by atlassian Bot

Loading

netlify Bot commented Jan 22, 2026 •

edited

Loading

netlify Bot commented Jan 22, 2026 •

edited

Loading