Connect analytics

GoalLink to this section

Show the client analytics in Admin. The Systhema analytics dashboard reads a provider's API; it does not install that provider's visitor tracking script.

1. Choose the providerLink to this section

The built-in providers are GA4, Plausible, Umami, Matomo and Fathom. Read Analytics providers for credentials and metric availability.

The Payload starter's src/payload/analytics.ts reads the environment and supplies a typed provider. For Plausible, configure:

SYSTHEMA_ANALYTICS_PROVIDER=plausible
SYSTHEMA_ANALYTICS_SITE_ID=example.com
SYSTHEMA_ANALYTICS_API_KEY=replace-with-private-stats-api-key

Use the domain registered with the provider. Keep the API key server-side; it is not a NEXT_PUBLIC_* variable.

2. Forward the configurationLink to this section

The starter already imports analytics and places it in userSysthemaConfig. In an older project, add a module like this and import its export there:

import type { SysthemaAnalyticsOptions } from '@systhemaui/payload'

export const analytics: SysthemaAnalyticsOptions | false =
  process.env.SYSTHEMA_ANALYTICS_API_KEY && process.env.SYSTHEMA_ANALYTICS_SITE_ID
    ? {
        provider: {
          source: 'plausible',
          apiKey: process.env.SYSTHEMA_ANALYTICS_API_KEY,
          siteId: process.env.SYSTHEMA_ANALYTICS_SITE_ID,
        },
      }
    : false

This module intentionally configures only Plausible. Preserve the starter's provider switch if the deployment must support several providers. A bare analytics: true cannot provide credentials.

3. Verify collection and consent separatelyLink to this section

Follow the provider's current installation instructions for visitor tracking. Add only the tracking requested for the project and integrate its consent behavior with the site's banner.

Read Cookie consent and Cookie scanner. Static scanning cannot see every cookie created by a script at runtime. Inspect a fresh session before and after consent, including relevant widget interactions.

Do not put private Stats API credentials in a visitor script. A dashboard API connection and a tracking script have different credential requirements.

4. Verify the dashboardLink to this section

pnpm sync
systhema doctor

Restart the application after changing environment values. Sign in with an account allowed to view analytics. Choose a period that has data and compare the numbers with the provider dashboard. Unsupported metrics may be unavailable rather than zero.

Check your workLink to this section

• The selected provider and site identifier match the client property.
• No API secret appears in frontend code or public environment variables.
• Tracking fires under the intended consent conditions.
• Admin metrics correspond to the selected period and site.
• The client owns the provider account and recovery details.

See Analytics dashboard and Analytics reference.