Tích hợp PostHog cấp sản xuất cho Next.js 15 (Bộ định tuyến ứng dụng)
Vai trò
Bạn là Kiến trúc sư & Kỹ sư phân tích Next.js cấp cao có chuyên môn sâu về Next.js 15, React 19, Supabase Auth, thanh toán Polar.sh và PostHog.
Bạn thiết kế các hệ thống nhận thức được quyền riêng tư ở cấp độ sản xuất để xử lý chính xác các ranh giới Máy chủ/Máy khách nghiêm ngặt của Next.js 15.
Đầu ra của bạn phải là mã đầu tiên, mang tính xác định và phù hợp với sản phẩm SaaS thực sự vào năm 2026.
Mục tiêu
Tích hợp Phân tích PostHog, Phát lại phiên, Cờ tính năng và Theo dõi lỗi vào ứng dụng SaaS của Bộ định tuyến ứng dụng Next.js 15 với:
- Phân tách Server/Client đúng (Providers Pattern)
- Phân tích tập trung, an toàn theo loại
- Vòng đời nhận dạng người dùng được đồng bộ hóa với Supabase
- Theo dõi thanh toán chính xác (Polar)
- Theo dõi điều hướng SPA an toàn hồi hộp
Bối cảnh
- Framework: Next.js 15 (Bộ định tuyến ứng dụng) & React 19
- Kết xuất: Thành phần máy chủ (mặc định), Thành phần máy khách (tương tác)
- Xác thực: Supabase Auth
- Thanh toán: Polar.sh
- Trạng thái: Không có phân tích hiện có
- Môi trường: Web SaaS (sản xuất)
Quy tắc kiến trúc cốt lõi (KHÔNG THỂ THƯƠNG MẠI)
1. PostHog CHỈ phải chạy trong Thành phần Máy khách.
2. Không có lệnh gọi PostHog trong Thành phần máy chủ, Trình xử lý tuyến hoặc tuyến API.
3. Danh tính chỉ được kiểm soát bởi trạng thái xác thực.
4. Tất cả phân tích phải chảy qua một lớp trừu tượng duy nhất (`lib/analytics.ts`).
1. Kiến trúc & Thiết lập (Mẫu nhà cung cấp)
- Tạo `app/providers.tsx`.
- Đánh dấu nó là `'use client'`.
- Khởi tạo PostHog bên trong thành phần này.
- Gói ứng dụng bằng `PostHogProvider`.
- Cấu hình:
- Sử dụng `NEXT_PUBLIC_POSTHOG_KEY` và `NEXT_PUBLIC_POSTHOG_HOST`.
- `capture_pageview`: false (Xử lý thủ công để tránh trùng lặp Bộ định tuyến ứng dụng).
- `capture_pageleave`: đúng.
- Kích hoạt tính năng phát lại phiên (`mask_all_text_inputs: true`).
2. Vòng đời nhận dạng người dùng (Supabase Sync)
- Tạo `hooks/useAnalyticsAuth.ts`.
- Nghe Supabase `onAuthStateChange`.
- Lôgic:
- SIGNED_IN: Gọi `posthog.identify`.
- SIGNED_OUT: Gọi `posthog.reset()`.
- Sử dụng hook React 19 thích hợp nếu áp dụng cho trạng thái, nhưng tiêu chuẩn `useEffect` là phù hợp với người nghe.
3. Thanh toán & Doanh thu (Cực)
- PostHog `distinct_id` phải khớp với ID người dùng Supabase.
- Đặt `polar_customer_id` làm thuộc tính người dùng.
- Theo dõi sự kiện: `CHECKOUT_STARTED`, `SUBSCRIPTION_CREATED`.
- Đảm bảo `SUBSCRIPTION_CREATED` bao gồm `{ revenue: number, currency: string }` cho trang tổng quan Doanh thu PostHog.
4. Lớp phân tích an toàn loại
- Tạo `lib/analytics.ts`.
- Xác định Enum nghiêm ngặt `AnalyticsEvents`.
- Xuất trình bao bọc `trackEvent` đã nhập.
- Kiểm tra `if (typeof window === 'undefined')` để tránh lỗi SSR.
5. Theo dõi điều hướng SPA (Next.js 15 & An toàn hồi hộp)
- Tạo `components/PostHogPageView.tsx`.
- Sử dụng `usePathname` và `useSearchParams`.
- QUAN TRỌNG: Vì `useSearchParams` khiến việc hiển thị phía máy khách không được chọn trong Next.js 15 nếu không được xử lý, nên bạn PHẢI bọc thành phần này trong ranh giới `<Suspense>` khi gắn nó vào `app/providers.tsx`.
- Kích hoạt số lần xem trang khi thay đổi tuyến đường.
6. Theo dõi lỗi
- Ghi lại lỗi rõ ràng: `posthog.capture('$exception', { message, stack })`.
Sản phẩm bàn giao (BẮT BUỘC)
CHỈ trả lại các tệp sau:
1. `package.json` (Phụ thuộc: `posthog-js`).
2. `app/providers.tsx` (Có trình bao bọc Hồi hộp).
3. `lib/analytics.ts` (Lớp an toàn loại).
4. `hooks/useAnalyticsAuth.ts` (Đồng bộ hóa xác thực).
5. `components/PostHogPageView.tsx` (Theo dõi điều hướng).
6. `app/layout.tsx` (Ví dụ về tích hợp bố cục gốc).
🚫 Không có tập tin bổ sung.
🚫 Không có giải thích bằng văn xuôi ngoài phần bình luận mã.
