Analytics & Traffic

SaaSyBase supports provider-backed traffic analytics for the admin dashboard, plus first-party visit tracking for self-hosted visibility inside the app.

Traffic analytics providers

The admin traffic dashboard can read from either Google Analytics 4 or PostHog. The active provider is selected with TRAFFIC_ANALYTICS_PROVIDER.

External browser tracking is intentionally disabled on /admin routes. Admin traffic reporting still works through the backend analytics adapter and first-party visit tracking.

That split is deliberate: admin sessions are usually operational traffic, not customer traffic. Excluding them keeps product metrics cleaner and avoids adding extra browser trackers in the most sensitive back-office screens.

Tip

Choose GA4 when you want Google's native engagement and new-user metrics. Choose PostHog when you want a more flexible product analytics stack without a Plausible subscription.

Variable	Required	Purpose
TRAFFIC_ANALYTICS_PROVIDER	Optional	Selects `google-analytics` or `posthog` for `/admin/traffic`
NEXT_PUBLIC_GA_MEASUREMENT_ID	Yes	Loads the client GA snippet
GA_PROPERTY_ID	Google only	Tells the server which GA4 property to query
GA_SERVICE_ACCOUNT_CREDENTIALS_B64	Google only	Base64-encoded Google service account JSON
GA_DATA_API_CACHE_SECONDS	Optional	Caches analytics reads on the server
POSTHOG_PROJECT_ID	PostHog only	Project ID used for Query API reads
POSTHOG_PERSONAL_API_KEY	PostHog only	Personal API key with query:read scope
POSTHOG_APP_HOST	Optional	App host for Query API requests, e.g. `https://us.posthog.com`
NEXT_PUBLIC_POSTHOG_KEY	PostHog only	Client-side Project token shown in the PostHog dashboard
NEXT_PUBLIC_POSTHOG_HOST	Optional	Client-side API host, e.g. `https://us.i.posthog.com`

Google Analytics 4 setup

Official docs: GA4 Data API docs and Google Analytics 4 setup help.

Create a Google Cloud service account with analytics read access.
Add that service account email to the GA4 property with Viewer or higher access.
Base64-encode the JSON credentials file and store it in GA_SERVICE_ACCOUNT_CREDENTIALS_B64.

base64 -i key.json

PostHog setup

Official docs: PostHog JavaScript and PostHog Query API.

Set TRAFFIC_ANALYTICS_PROVIDER to posthog.
Create a personal API key with query:read permission and store it in POSTHOG_PERSONAL_API_KEY.
Copy your PostHog project ID into POSTHOG_PROJECT_ID.
Expose the client Project token from the PostHog dashboard as NEXT_PUBLIC_POSTHOG_KEY.
Set NEXT_PUBLIC_POSTHOG_HOST and POSTHOG_APP_HOST if you are not using the default US cloud hosts.
Expect browser-side pageview capture on public/app routes, but not on /admin.

Note

This adapter uses PostHog pageviews plus Query API aggregations. The dashboard swaps GA4-only cards for supported PostHog metrics such as bounce rate, views per visit, and estimated engaged visits.

In the shipped adapter, GA4-only cards such as new users, engaged sessions, and engagement rate are replaced by PostHog-supported or derived metrics like bounce rate, views per visit, and estimated engaged visits.

First-party visit tracking

The app also ships with built-in visit tracking via lib/visit-tracking.ts and the VisitLog model. This powers admin traffic views even if you do not connect an external analytics provider.

Traffic is recorded through POST /api/internal/track-visit and intentionally skips API routes, static files, admin pages, and bot traffic.

Note

Choose first-party tracking when you want privacy-friendlier, app-owned route visibility. Choose an external provider when you need richer acquisition, attribution, or event reporting.

What metrics you get

Area	Examples
Provider-backed metrics	Total visits, unique visitors, page views, duration, pages, referrers, countries, device mix
Provider-specific metrics	GA4: new users and engagement rate. PostHog: bounce rate, views per visit, estimated engaged visits
Self-hosted visibility	Visit trends and first-party route activity via VisitLog

Where to view analytics

/admin/analytics for app-owned revenue, user, and subscription analytics
/admin/traffic for provider-backed traffic reporting
/api/admin/analytics and /api/admin/traffic for server-side data access

Operational notes

Note

GA_DATA_API_CACHE_SECONDS controls server-side caching for GA4 reads and defaults to 30 seconds in the shipped implementation. Lower it when you need fresher dashboards, and raise it when you want to reduce API quota usage.

Note

If you set NEXT_PUBLIC_GA_MEASUREMENT_ID in development, the tracking snippet still loads. Use a dev GA property locally if you do not want to contaminate production analytics.

The repository still contains some older Umami operational notes in ops/, but the supported path is Google Analytics, PostHog, and first-party visit tracking.

If you are deciding where to store analytics credentials, see Secrets & Providers.