Skip to content

deferred_third_parties_debug.md

Latest commit

 

History

History
73 lines (59 loc) · 5.82 KB

deferred_third_parties_debug.md

File metadata and controls

73 lines (59 loc) · 5.82 KB

DeferredThirdParties Debug Log

Summary

This debug log documents the troubleshooting work for the DeferredThirdParties component in the DealScale project. The component is responsible for loading Google Analytics, Google Tag Manager, Microsoft Clarity, and Zoho SalesIQ scripts in a deferred manner for performance optimization.

Issues Encountered

  1. Undefined Environment Variables: NEXT_PUBLIC_* vars were not loading in client-side code, causing scripts to not initialize.
  2. Deferral Logic Not Triggering: Scripts were not loading even after page load or user interaction due to deferral issues.
  3. Inconsistent Loading: Env vars loaded sometimes but glitchy, leading to unreliable script injection. Sometimes the API returned "No providers configured" when vars were undefined, indicating server-side loading issues.

Root Causes

  • Env Vars Not Set: Initially, vars were missing from .env file.
  • Server Restart Required: Next.js loads env vars on server start; updates require restart.
  • Deferral Too Strict: Original deferral waited for specific events that weren't firing in all environments (e.g., private windows).
  • Client-Side Access: Vars must be NEXT_PUBLIC_* for browser access, and server must be restarted after changes.

Steps Taken

  1. Initial Investigation: Added debug logging to track env var loading and deferral state.
  2. Fixed Deferral Logic: Initially set to load immediately for testing, then reverted to user-activity-based deferral for performance.
  3. Added API Route for Security: Created /api/init-providers to fetch IDs server-side, reducing client exposure.
  4. Updated Debug Logs: Added notes about glitchy behavior and reduced verbosity.
  5. Environment Variable Setup: Guided user to add vars to .env and restart server.

Current Status

  • Deferral Logic: Reverted to wait for page load or user interaction (scroll, click, keydown) with idle callback/setTimeout backup.
  • Security: Uses server-side API for ID fetching.
  • Performance: Loads scripts only after user engagement, improving initial page load.
  • Debugging: Logging initially indicated glitchy env var loading, likely due to server restart issues. Resolved by restarting the dev server after .env updates.

Key Logs and Insights

  • Env Vars Undefined: envClarityId: undefined, envZohoCode: undefined - Fixed by adding to .env and restarting server.
  • Deferral Trigger: useDeferredLoad: Enabling load after interaction or load event.
  • Script Injection: Clarity: Script injected successfully after conditions met.
  • Glitchy Note: Added to debug log: "Sometimes works but glitchy - env vars loading inconsistently".
  • Inconsistent API Response: Fetched provider data { error: "No providers configured" } when vars are undefined server-side, indicating reload issues.

Recommendations

  1. Always Restart Server: After updating .env, stop and restart npm run dev.
  2. Test in Multiple Browsers: Deferral may behave differently in private/incognito modes.
  3. Monitor Network Tab: Verify script requests (e.g., clarity.ms, googletagmanager.com) after interaction.
  4. Remove Debug Logs in Production: Current logs are for debugging; remove for production builds.
  5. If Issues Persist: Check .env syntax, ensure vars are defined, and verify the server is loading them.

2025 Hardened Configuration

  • Private-first env handling: Runtime config now prefers private server env vars (CLARITY_PROJECT_ID, GOOGLE_ANALYTICS_ID, GOOGLE_TAG_MANAGER_ID, ZOHO_SALES_IQ_WIDGET_CODE) and only falls back to the legacy NEXT_PUBLIC_* names during development. The shared getAnalyticsConfig helper validates all IDs with Zod, tracks when fallbacks are used, and reports structured issues back to callers without leaking secrets.
  • API error signalling: /api/init-providers returns 503 with structured error details when configuration is invalid. Successful responses include any warnings plus a map of fallbacks that were used so the client can surface console hints.
  • Deferred loading coverage: useDeferredLoad now listens for visibilitychange, pageshow, and pointermove, and enforces a five-second timeout so analytics boot even in background tabs or incognito windows.
  • Operational guardrails: tools/checks/check-analytics-env.ts warns when the secure env vars are missing (or when the project is relying on NEXT_PUBLIC_* fallbacks) and runs automatically before pnpm dev, pnpm dev-turbo, or pnpm start.

Env mapping cheat sheet

Provider Preferred env Dev fallback
Microsoft Clarity CLARITY_PROJECT_ID NEXT_PUBLIC_CLARITY_PROJECT_ID
Google Analytics GOOGLE_ANALYTICS_ID NEXT_PUBLIC_GOOGLE_ANALYTICS
Google Tag Manager GOOGLE_TAG_MANAGER_ID NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID
Zoho SalesIQ ZOHO_SALES_IQ_WIDGET_CODE NEXT_PUBLIC_ZOHOSALESIQ_WIDGETCODE

Restart the Next.js dev server after editing any of these values so the process reloads the updated environment.

Files Modified

  • src/components/providers/DeferredThirdParties.tsx: Hardened fetch + retry logic, extended deferral triggers, analytics prop wiring.
  • src/components/providers/useDeferredLoad.ts: Shared deferred-loading hook that covers visibility/background events.
  • src/lib/analytics/config.ts: Private-first env loader with validation, fallback tracking, and structured issues.
  • src/app/api/init-providers/route.ts: Server route now consumes the shared config helper and signals errors with HTTP 503.
  • tools/checks/check-analytics-env.ts: Pre-dev script that highlights missing or fallback env vars.
  • .env: Updated with NEXT_PUBLIC_* vars (user-added).

Next Steps

  • Test in production environment.
  • Optimize deferral timeouts if needed.
  • Integrate with monitoring tools for script load failures.