Opportunity Recommendations

Opportunities answer the operator question: Know what to review next. They turn existing HitKeep analytics into saved, evidence-backed recommendation records for conversion signals, traffic sources, Web Vitals performance issues, AI visibility gaps, search visibility, and setup gaps worth reviewing.

The important boundary is simple: detectors decide what exists. AI is optional and may only help choose approved localized copy from cited evidence.

What the page shows

The Opportunities page ranks saved recommendations for the active site.

Each item includes:

type, score, confidence, and workflow status
impact label and value based on the detector evidence
the dashboard route or source the recommendation points to
cited evidence such as checkout starts, orders, AI crawler requests, pageviews, sessions, or tracked events
the next action text rendered from localization keys and interpolation params

The workflow statuses are:

Status	Meaning
`new`	Generated and not yet triaged.
`saved`	Kept for follow-up.
`done`	Marked complete by a permitted user.
`dismissed`	Hidden from the normal active list.

Generation model

Generation runs in two phases.

HitKeep loads analytics for the selected site and date range.
Deterministic detectors create candidate Opportunities.
If AI is enabled, configured, and inside the local budget, HitKeep asks the provider to select approved copy keys and cite evidence for each candidate.
HitKeep validates the output and saves only the final structured recommendation.

If AI is disabled or not configured, detector output is still saved. The dashboard can still show localized recommendations because the detector output already uses translation keys and params.

Current detector families

The first detector set reads data HitKeep already stores:

Detector type	Input data	When it appears
`checkout_conversion`	Ecommerce summary	Checkout starts exist and checkout conversion is below the detector threshold.
`ai_visibility`	AI fetch overview plus optional site traffic support	AI crawler requests exist for the site.
`traffic_quality`	Site overview stats and top sources	The site has actionable source traffic with source-specific counts, enough sample size, and meaningful share in the selected range.
`performance`	Web Vitals p75 summary plus page breakdowns	Web Vitals samples show a poor or needs-improvement metric with enough aggregate evidence.
`search_visibility`	Imported Search Console aggregates	Impressions exist with room to improve clicks or position.
`conversion_signal`	Site traffic, events, ecommerce, and existing setup	Tracked events exist but the site still lacks a clear conversion signal.
`setup_goal_suggestion`	Setup evidence from events and goals	A conversion-like event repeats enough times and no matching goal exists.
`setup_funnel_suggestion`	Setup evidence from paths, events, and funnels	A likely path-to-event conversion flow appears and no matching funnel exists.

The detectors assign opportunity type, impact, confidence, score, status, evidence, and cited evidence IDs. AI stays inside the allowlisted detector contract and cannot publish an unsupported opportunity type.

HitKeep does not create a placeholder Opportunity for a site with no usable signal. Setup suggestions require direct aggregate evidence, such as repeated conversion-like events or a repeated path-to-event flow. Performance recommendations require Web Vitals samples and cite aggregate metrics, not raw browser debug fields. If a new site has no pageviews, events, ecommerce activity, Web Vitals samples, AI fetches, Search Console rows, or setup evidence yet, generation returns no_opportunities.

Localization-safe API contract

Opportunity API responses do not return full translated prose as the contract. They return keys and params that the dashboard translates.

Important fields include:

Field	Purpose
`title_key`, `summary_key`, `action_key`, `digest_key`	Translation keys for customer-visible copy.
`copy_params`	Interpolation values for those keys, for example conversion rate, source, source-specific visits, total pageviews, path, or estimated search clicks.
`impact_label_key` and `impact_value`	Localized impact label plus detector value.
`route_label_key`, `route_params`, and `route_icon`	Where the UI points the user next.
`evidence[].label_key`, `evidence[].value`, and `cited_evidence_ids`	The evidence shown to the user and the evidence IDs the copy is allowed to reference.
`detector_version`	The detector contract that produced the record.
`ai_run_id`	Present on authenticated site responses when AI enrichment succeeded. Omitted from shared dashboard responses.

This keeps the API useful for any supported dashboard language and avoids storing customer-facing English as the durable product contract. Opportunity recommendations do not expose monthly_upside or financial promise fields; ecommerce analytics pages can still report factual revenue metrics.

Saved Opportunities can be included in the regular daily or weekly email digest. There is no separate “Opportunities email” to configure. GET /api/sites/{id}/opportunities/digest-preview?frequency=weekly previews the safe digest payload for a site, using the same key-and-placeholder contract without persisting a new run.

Permissions

Action	Required permission
List saved Opportunities	`site.view`
Generate or regenerate Opportunities	`site.manage_data`
Save, dismiss, or mark done	`site.manage_data`
View through a share link	Valid share token for that site. The response omits internal AI run and team fields.
Configure AI provider settings	Instance owner or admin operating the runtime configuration.

API clients and MCP clients can read saved Opportunities only when their token can view the site.

Enable AI enrichment

AI enrichment is disabled by default. Configure the HitKeep route and local budgets on the HitKeep process. Configure provider credentials with the selected goAI provider’s own environment variables. Use the goAI supported providers documentation for provider-specific auth and endpoint variables.

HITKEEP_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai
HITKEEP_AI_MODEL=your-model-id
OPENAI_API_KEY=your-provider-key
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440

The full setup guide is AI Model Configuration. It covers model choice, HitKeep route fields, goAI provider credential variables, token budgets, and System Status behavior.

For OpenAI-compatible gateways such as LiteLLM or Bifrost, set a HitKeep base URL. Authentication is optional for the generic compatible provider. Set HITKEEP_AI_API_KEY only when your gateway requires a bearer token.

HITKEEP_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai-compatible
HITKEEP_AI_MODEL=your-routing-model
HITKEEP_AI_BASE_URL=https://ai-gateway.example/v1

For region-scoped providers, use the provider’s native environment. For example, Bedrock uses AWS credentials and region variables:

HITKEEP_AI_ENABLED=true
HITKEEP_AI_PROVIDER=bedrock
HITKEEP_AI_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION=eu-central-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

See the AI Model Configuration guide for setup examples and the Configuration Reference for the full provider list, defaults, timeout, and budget fields.

Budget and status

HitKeep enforces local request and token budgets before provider calls. This is separate from provider or gateway limits.

HITKEEP_AI_TOKEN_LIMIT is the local budget for counted provider tokens in the configured window. It is not the model context window. The Opportunities enrichment call expects a compact JSON object and caps provider output at 900 tokens before validation.

The admin AI status endpoint and System Status page can show:

disabled
not_configured
configured
budget_exhausted
needs_attention

Safe error categories include auth_failed, rate_limited, timeout, budget_exhausted, invalid_output, canceled, and provider_error.

Raw prompts, raw provider responses, raw external error bodies, and provider secrets are not returned by status endpoints.

Privacy and audit boundary

AI run records keep operational metadata:

team, site, actor, and feature
provider and model label
prompt template version
cited evidence IDs
input and output hashes
final validated structured output
token and request usage when available
lifecycle events such as request start, request finish, tool call start, tool call finish, latency, status, and safe error category

HitKeep does not persist raw prompts or raw provider payloads for Opportunities. Provider secrets are redacted from logs and status responses.

Email digests

Opportunities are part of the regular report system. When saved recommendations are ready for a site, the digest renderer can include the same localized title/action keys, params, score, confidence, route hints, and cited aggregate evidence that the dashboard shows.

The email path does not trigger a new AI run and does not include raw prompts, raw provider output, or unrestricted tool data. It reads saved records and renders the same safe customer-visible fields.

Saved Opportunities can appear outside the dashboard through controlled surfaces:

MCP exposes saved Opportunities as final safe records for visible sites.
Share links can read saved Opportunities for the shared site, without internal team or AI run fields.
Site takeout includes saved Opportunities and safe AI run metadata, but excludes provider secrets and raw AI payloads.

These surfaces do not expose unrestricted AI tools, raw hit/session rows, IP addresses, user agents, raw prompts, or raw provider responses.