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

2.6 KiB

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.