Kernlift

Add analytics and support chat

Load Google Analytics, Umami, Plausible, Clarity or the Crisp chat widget on every page, check the connection and read statistics by country.

When you save a provider's identifier in the admin console, its script loads on every page. When you also save its API credential, you can pull a report to confirm the connection. Every provider is optional and independent, and none reads environment variables.

Before you begin

  • An account with each provider you want, with a site or project for your domain.
  • An admin account with config.write. config.read opens the page but cannot save, pull reports or send a test event.
  • For statistics by country, countries.read.

Each provider has two parts: a public identifier that loads the script, and an API credential used only when an admin pulls a report.

ProviderWhat it addsLoads the scriptNeeded for report pulls
Google AnalyticsPage views and events in GA4Google Analytics IDGA property ID and GA Data API access token
Google AdsThe Google tag for your Ads accountGoogle Ads IDNot pulled
UmamiPrivacy-focused analytics, cloud or self-hostedUmami website IDUmami API key
PlausiblePrivacy-focused analytics, cloud or self-hostedPlausible domainPlausible API key
Microsoft ClarityHeatmaps and session recordingsClarity project IDClarity API token
CrispLive chat widgetCrisp website IDNot pulled

Create a site with the analytics provider

ProviderChoose it for
Google AnalyticsGA4 page views and report pulls
Google AdsLoad the Ads tag and configure a conversion label
UmamiMeasure visits in Umami Cloud or on your host
PlausibleDomain-based traffic statistics
Microsoft ClarityHeatmaps and session recordings
CrispEmbed the chat widget

Connect a provider

Open Analytics Config

Go to Settings → Analytics Config (/admin/config/analytics). The form has one section per provider: Google, Umami, Plausible and Clarity / Crisp. The Runtime checks panel shows whether each identifier is saved.

Fill in the fields for your provider

Use the field mapping in your provider’s guide above.

Token and API key fields are never shown again. Their placeholder reads Leave blank to keep current token. Clearing an identifier removes that provider's script, and clearing a base URL or script URL restores its default.

Save

Click Save analytics config. The page shows Analytics provider configuration saved. and the Runtime checks panel updates.

No consent banner

Once saved, each configured script loads on every page of the site, including the admin console, from the next page load. There is no consent banner or per-page switch. If you need visitor consent before tracking, add it to your application before enabling a provider.

Pull provider reports

Pull

On Analytics Config, in the Provider reports card, click Pull reports.

Read the result

Each of Google Analytics, Umami, Plausible and Clarity shows Passed with a returned row count, Failed with the provider's HTTP status, or Not configured naming the missing fields. A provider is contacted only when both its identifier and its API credential are saved. The current Clarity request asks for 7 days, but its Data Export API accepts only 1–3 days. The provider may therefore reject that report check, which does not show that the script is absent.

Record your own events

To try it without code, use the Send a test event card on Analytics Config: keep the defaults or choose a Category and Event name, and click Send event. Event recorded. confirms it was stored.

From trusted server code, record product events the same way. The function performs no permission check, so never expose it directly to the browser:

src/server/services/example.service.ts
import { trackAnalyticsEvent } from "@/server/services/analytics-support.service";

await trackAnalyticsEvent({
  type: "product",
  name: "project_created",
  userId: user.id,
  path: "/app/projects",
  locale: "en",
  value: 1,
});

type is one of product, revenue, ai, api, acquisition, support or retention. Events stay in your database and are not sent to external providers.

For the separate account and settled-order breakdown by country, see Countries and regions. That page reads your own account and order records and does not use a provider report.

Verify

  1. Open a public page such as / or /pricing in a private window, with ad blockers off.
  2. View the page source and look for the script: googletagmanager.com/gtag/js for Google Analytics or Google Ads, a script with your data-website-id for Umami, a script with your data-domain for Plausible, clarity.ms/tag for Clarity and client.crisp.chat/l.js for Crisp.
  3. Confirm the visit appears in the provider's real-time view. The Crisp chat bubble appears in the page corner.
  4. /setup lists Analytics provider as ready once a Google Analytics, Umami, Plausible or Clarity identifier is saved.

In the repository, pnpm validate:analytics checks the settings, events, report pulls and permissions.

Troubleshooting

Saving fails with a format error

The Google Analytics ID must look like G-XXXXXXXX, the property ID must be numeric, and the Google Ads ID must look like AW-XXXXXXXX. Nothing is saved until all three are valid.

A provider report shows Failed

The provider rejected the request. The report shows the HTTP status and the start of the response. For Google Analytics, check that the access token has not expired and can read the property.

No script appears on the page

The identifier is empty, the page was not reloaded after saving, or an ad blocker removed it. Check the Runtime checks panel, then reload with extensions off.

The Crisp widget shows "Invalid website"

The saved Crisp website ID does not match a website in your Crisp account. Copy it from Crisp and save again.

Reference

Next steps