---
title: "HitKeep 2.5.0: Web Vitals, Opportunities, And Subdirectory Installs | HitKeep"
description: "HitKeep 2.5.0 prepares Web Vitals analytics, Opportunity Recommendations, subdirectory installs, Web Vitals MCP aggregates, and dashboard polish."
canonical: "https://hitkeep.com/blog/hitkeep-2-5-0/"
---

[← All posts](https://hitkeep.com/blog/)

# HitKeep 2.5.0: Web Vitals, Opportunities, And Subdirectory Installs

Published May 13, 2026·[Pascale Beier, HitKeep maintainer](https://github.com/pascalebeier)·5 min read

HitKeep 2.5.0 is in release-candidate review for [Web Vitals analytics](https://hitkeep.com/guides/analytics/web-vitals/) and [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/). 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](https://hitkeep.com/_astro/analytics-web-vitals.sOa6lsyi_ZO3dtx.webp)

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](https://hitkeep.com/_astro/analytics-opportunities.SThTpN9l_R3exK.webp)

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

- **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

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

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:

```
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.

```
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](https://hitkeep.com/guides/admin/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

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

- [Web Vitals Analytics](https://hitkeep.com/guides/analytics/web-vitals/)
- [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/)
- [AI Model Configuration](https://hitkeep.com/guides/admin/ai-model-configuration/)
- [AI model configuration reference](https://hitkeep.com/reference/configuration/#optional-ai-model-configuration)
- [Public URL path prefixes](https://hitkeep.com/reference/configuration/#public-url-path-prefixes)
- [Tracker Architecture](https://hitkeep.com/guides/tracking/tracker-architecture/)
- [System Status and Settings](https://hitkeep.com/guides/admin/system-administration/)
- [Roles and Permissions](https://hitkeep.com/guides/admin/permissions/)
- [MCP Analytics Access](https://hitkeep.com/guides/integrations/mcp/)
- [Open Exports and Takeout](https://hitkeep.com/guides/data/takeout/)

Managed option

## Run HitKeep without the ops burden.

HitKeep Cloud runs the same single binary in region-pinned EU or US infrastructure, with managed updates and backups.

[Start free in HitKeep Cloud](https://cloud.hitkeep.eu/signup?utm_source=hitkeep_docs&utm_medium=website&utm_campaign=cloud_signup&utm_content=content_cta&plan=free&billing=monthly)[Self-host instead](https://hitkeep.com/guides/installation/)

[← OlderHitKeep 2.4.2: Site Export Dropdown Fix](https://hitkeep.com/blog/hitkeep-2-4-2/)[Newer →HitKeep 2.5.1: Dashboard Refresh And Clearer API-Client Grants](https://hitkeep.com/blog/hitkeep-2-5-1/)