Skip to content
HitKeep
Start in Cloud
Blog

HitKeep 2.5.0: Web Vitals, Opportunities, And Subdirectory Installs

- 6 min read - 1100 words
Pascale Beier
HitKeep maintainer

HitKeep 2.5.0 is in release-candidate review for Web Vitals analytics and Opportunity Recommendations. The release candidate adds opt-in LCP, INP, CLS, FCP, and TTFB reporting beside traffic analytics, plus a saved recommendations inbox for setup gaps, traffic signals, search visibility, AI visibility, ecommerce activity, conversion signals, and performance issues backed by aggregate evidence already in HitKeep.

It also hardens self-hosted deployments that mount HitKeep below an existing domain path, such as https://www.example.net/hitkeep/. Dashboard navigation, static assets, API calls, the API reference, tracker bundles, browser ingest, email links, share links, billing redirects, and OAuth callbacks now derive their public paths from HITKEEP_PUBLIC_URL.

The product promise is deliberately narrow: HitKeep shows privacy-preserving performance signals and evidence-backed recommendations. It does not collect Web Vitals attribution payloads, promise revenue lift, claim financial upside, or infer causal attribution.

HitKeep Web Vitals report showing p75 metric cards, threshold bars, rating mix bars, filters, and the trend chart
Web Vitals cards show p75 values, thresholds, rating mix, and the selected metric trend without enabling Web Vitals by default.
HitKeep Opportunities page showing prioritized recommendation cards with evidence, status filters, and a selected recommendation detail drawer
Opportunity cards use stable translation keys and cited aggregate evidence, so the same saved recommendation can render safely in every supported dashboard language.

What Is Prepared

Section titled “What Is Prepared”
  • Opt-in Web Vitals collection: the default hk.js snippet stays lean. Sites load the same-origin hk-vitals.js split bundle only when Web Vitals are enabled in tracking settings or data-enable-web-vitals="true" is present.
  • Web Vitals dashboard: site teams can inspect p75 cards, threshold bars, rating mix, trends, searchable path selection, paginated page breakdowns, and browser, country, language, and device context for LCP, INP, CLS, FCP, and TTFB.
  • Privacy-preserving samples: HitKeep stores metric, value, server-derived rating, normalized path, navigation type, session/page IDs, tracker source/version, and server receipt time. It strips query strings and hashes and does not store attribution/debug payloads, selectors, text, or resource URLs.
  • Lifecycle coverage: Web Vitals samples are tenant-local and covered by site deletion, user deletion, archival, retention, takeout exports, and read-only MCP aggregate access.
  • Opportunity inbox: every site can list saved recommendations, filter by status, open the evidence drawer, dismiss items, mark them done, and regenerate them when the user has site.manage_data.
  • Evidence-first generation: deterministic detectors decide the candidate type, impact, confidence, score, status, route params, and evidence IDs. Web Vitals detectors can create Performance Opportunities from poor or needs-work metric evidence. AI is optional and can only decorate the detector-approved candidate.
  • Provider-agnostic AI model configuration: self-hosted operators can configure their chosen provider, model, gateway route, timeout, and local budgets through HITKEEP_AI_* settings without dashboard-secret editing in this first slice.
  • Local budgets and audit records: HitKeep enforces request and token caps before provider calls, records safe run metadata, stores lifecycle events, and avoids persisting raw prompts or raw provider payloads.
  • System Status visibility: instance owners can see whether AI is enabled and configured, which provider/model label is active, whether the config is cloud-managed or self-hosted, current usage and cap state, and the last safe success/error category.
  • Subdirectory install support: operators can set HITKEEP_PUBLIC_URL to a path-prefixed URL. HitKeep serves the dashboard base href, app-owned static assets, API reference iframe, hk.js, hk-vitals.js, ingest routes, and generated public links below that prefix.
  • Public-safe surfaces: saved Opportunities appear in dashboard APIs, share mode, takeout exports, read-only MCP output, and the regular daily, weekly, or monthly email reports without exposing provider secrets or unrestricted tool execution. Web Vitals dashboard APIs and MCP tools return aggregate reporting data only.
  • Localization-safe API: customer-facing copy is stored as translation keys plus interpolation params. The API does not persist full English recommendation text as the durable contract.

Guardrails

Section titled “Guardrails”

Web Vitals collection is opt-in. HitKeep derives ratings on the server from standard thresholds, stores samples in the tenant analytics store, and keeps the tracker payload compact. The Web Vitals feature is for aggregate page-performance reporting, not user-level profiling or debugging traces.

Opportunity Recommendations use aggregate evidence only. Traffic-source recommendations must cite source-specific counts, not total site pageviews. Setup suggestions need a clear page, event, goal, or funnel signal and are suppressed when matching configuration already exists.

The validator rejects provider output that invents evidence IDs, adds trailing prose after JSON, uses removed money/upside params, references unsupported fields, or makes claims outside the detector contract.

Upgrade Guidance

Section titled “Upgrade Guidance”

Web Vitals are off by default. Enable them from Site Settings > Tracking for a site, or add data-enable-web-vitals="true" to that site’s tracking snippet. The main tracker only loads hk-vitals.js from the same origin when the opt-in flag is present.

For subdirectory installs, set HITKEEP_PUBLIC_URL to the full external URL, including the path prefix, and keep the reverse proxy route aligned with that prefix:

Terminal window
HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/

In path-prefix mode, public app and API routes are served below the configured prefix. Root /healthz and /readyz remain available for local probes.

Self-hosted instances can leave AI disabled. With HITKEEP_AI_ENABLED=false, HitKeep still runs deterministic detector logic and stores recommendations that do not need provider enrichment.

To enable provider enrichment on self-hosted instances, configure the HitKeep provider/model route, timeout, request cap, token cap, and budget window through HITKEEP_AI_* variables. Configure provider credentials with the selected goAI provider’s native environment variables.

Terminal window
HITKEEP_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai
HITKEEP_AI_MODEL=your-json-capable-model
OPENAI_API_KEY=provider_key_from_your_secret_store
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440

For OpenAI-compatible gateways, set HITKEEP_AI_PROVIDER=openai-compatible and HITKEEP_AI_BASE_URL for the gateway endpoint. Set HITKEEP_AI_API_KEY only if that gateway requires a bearer token. See AI Model Configuration for model-selection guidance, setup examples, token-budget sizing, and the System Status fields operators should verify before release.

Out Of Scope

Section titled “Out Of Scope”

This release candidate does not add Web Vitals attribution/debug fields, sampling controls, external performance vendors, share-link Web Vitals reports, dashboard-secret editing for provider keys, customer-defined detectors, write-capable MCP tools, or financial upside predictions. Ecommerce analytics can still report factual revenue metrics, but Opportunity Recommendations do not position themselves around money claims.

Read More

Section titled “Read More”
Designed & developed in Germany. Sovereign by default.