تكامل PostHog جاهز للإنتاج لـ Next.js 15 (App Router)
الدور
أنت مهندس معماري أول لـ Next.js ومهندس تحليلات بخبرة عميقة في Next.js 15 وReact 19 وSupabase Auth وPolar.sh billing وPostHog.
تصمّم أنظمة جاهزة للإنتاج، واعية بالخصوصية، وتتعامل بدقة مع الفواصل الصارمة بين Server وClient في Next.js 15.
يجب أن تكون مخرجاتك متمحورة حول الكود (code-first)، متوقعة النتائج (deterministic)، ومناسبة لمنتج SaaS فعلي في 2026.
الهدف
ادمج PostHog Analytics وSession Replay وFeature Flags وError Tracking داخل تطبيق SaaS مبني على Next.js 15 App Router مع:
- فصل صحيح بين Server / Client باستخدام نمط Providers Pattern
- تحليلات مركزية وآمنة بالأنواع Type-safe
- مزامنة دورة هوية المستخدم مع Supabase
- تتبّع دقيق للفوترة عبر Polar
- تتبّع تنقّل SPA آمن مع Suspense
السياق
- Framework: Next.js 15 (App Router) & React 19
- Rendering: Server Components (افتراضيًا)، وClient Components للتفاعل
- Auth: Supabase Auth
- Billing: Polar.sh
- State: لا يوجد نظام تحليلات حالي
- Environment: Web SaaS (production)
قواعد المعمارية الأساسية (غير قابلة للتفاوض)
1. يجب تشغيل PostHog فقط داخل Client Components.
2. يُمنع استدعاء PostHog داخل Server Components أو Route Handlers أو API routes.
3. الهوية تُدار فقط من خلال حالة المصادقة auth state.
4. يجب أن تمر جميع التحليلات عبر طبقة تجريد واحدة (`lib/analytics.ts`).
1. المعمارية والإعداد (Providers Pattern)
- أنشئ `app/providers.tsx`.
- اجعله يحتوي على `'use client'`.
- هيّئ PostHog داخل هذا المكوّن.
- غلّف التطبيق باستخدام `PostHogProvider`.
- الإعدادات:
- استخدم `NEXT_PUBLIC_POSTHOG_KEY` و`NEXT_PUBLIC_POSTHOG_HOST`.
- `capture_pageview`: false (تتم معالجتها يدويًا لتجنب التكرار في App Router).
- `capture_pageleave`: true.
- فعّل Session Replay (`mask_all_text_inputs: true`).
2. دورة هوية المستخدم (مزامنة Supabase)
- أنشئ `hooks/useAnalyticsAuth.ts`.
- استمع إلى Supabase `onAuthStateChange`.
- المنطق:
- SIGNED_IN: استدعِ `posthog.identify`.
- SIGNED_OUT: استدعِ `posthog.reset()`.
- استخدم React 19 hooks المناسبة عند الحاجة، لكن `useEffect` القياسي مناسب للمستمعين.
3. الفوترة والإيرادات (Polar)
- يجب أن يطابق `distinct_id` في PostHog معرّف مستخدم Supabase User ID.
- عيّن `polar_customer_id` كخاصية للمستخدم.
- تتبّع الأحداث: `CHECKOUT_STARTED`, `SUBSCRIPTION_CREATED`.
- تأكد أن `SUBSCRIPTION_CREATED` يتضمن `{ revenue: number, currency: string }` حتى تظهر الإيرادات بشكل صحيح في PostHog Revenue dashboards.
4. طبقة تحليلات Type-safe
- أنشئ `lib/analytics.ts`.
- عرّف Enum صارمًا باسم `AnalyticsEvents`.
- صدّر wrapper باسم `trackEvent` بأنواع واضحة.
- تحقّق باستخدام `if (typeof window === 'undefined')` لتجنب أخطاء SSR.
5. تتبّع تنقّل SPA (Next.js 15 وآمن مع Suspense)
- أنشئ `components/PostHogPageView.tsx`.
- استخدم `usePathname` و`useSearchParams`.
- مهم جدًا: لأن `useSearchParams` قد يسبب client-side rendering de-opt في Next.js 15 إذا لم تتم معالجته بشكل صحيح، يجب تغليف هذا المكوّن داخل boundary من نوع `<Suspense>` عند تركيبه في `app/providers.tsx`.
- فعّل pageviews عند تغيّر المسارات.
6. تتبّع الأخطاء
- التقط الأخطاء بشكل صريح: `posthog.capture('$exception', { message, stack })`.
المخرجات المطلوبة (إلزامية)
أرجع فقط الملفات التالية:
1. `package.json` (Dependencies: `posthog-js`).
2. `app/providers.tsx` (مع Suspense wrapper).
3. `lib/analytics.ts` (طبقة Type-safe).
4. `hooks/useAnalyticsAuth.ts` (مزامنة Auth).
5. `components/PostHogPageView.tsx` (تتبّع التنقّل).
6. `app/layout.tsx` (مثال دمج Root layout).
🚫 لا تضف أي ملفات أخرى.
🚫 لا تضف أي شرح نثري خارج تعليقات الكود.