Files
canina/scripts/seo-performance/CLARITY.md
T

18 lines
2.6 KiB
Markdown

# Clarity worker integration
Worker CLI now instantiates one shared Clarity collector and includes independent provenance in `sourceMetadata.clarity`. Uses the existing metadata contract; no backend column/schema changes. Default scope is project, never an article's measurement or keyword-caused conversions. Missing commerce linkage stays null; no commerce activation or purchase-error changes.
Run with `/opt/hermes/.venv/bin/python` (dotenv available) to read the provisioned `/opt/data/.env` token in-process without restart. Never pass the token on the command line. Regular CLI retains explicit local state and read-only behavior. Use the same durable `--state` path on future runs so cache/budget survives. The verification state is `/opt/data/clarity-worker-state.sqlite` outside Git; worker default `tracker.sqlite` is separate unless explicitly selected.
Read-only standalone verification:
```
/opt/hermes/.venv/bin/python verify_clarity.py --state /opt/data/clarity-worker-state.sqlite --receipt evidence/clarity-live-receipt.json
```
Only official GET endpoint, Bearer header, redirects off, connect/read timeouts 5/30s. No retries or pagination. API reports rolling 24/48/72h (default 3 days), UTC, not GSC's 14-day period. Max three valid dimensions, 1000 rows, ten attempted calls per UTC day/project **in the shared local state**. External callers/setup requests are not observable by this budget; HTTP429 is cached unavailable. Failed/pending collections are cached for the day too; crashed reservations intentionally remain unavailable rather than silently retrying. Project identifier is explicit; all callers for a project must use the same identifier/state.
Persist only allowlisted numeric aggregate fields; omit categorical/popular-page reports and arbitrary text. URL breakdown is opt-in via constructor; only an exact URL dimension hash can produce article scope. No URL normalization/inference, query strings or raw provider response persisted/logged. A row-limit boundary is disclosed as possibly truncated, not paginated. Missing/malformed responses remain unavailable with null metrics, not zero.
Evidence: seven initial RED failures for missing collector; full final worker suite recorded in `evidence/clarity-tests.txt`. Single real API request returned HTTP200 with nine allowlisted metric groups / nine aggregate rows. Sanitized receipt `evidence/clarity-live-receipt.json` contains shape/status only. Actual backend delivery of Clarity metadata was not attempted/verified; no deployment, push, cron changes or runtime restart. No article-specific Clarity coverage verified by the project-scoped live probe.