omtools v26.0.8 usage analytics integration
Date: 2026-09-30

Purpose
- Measure acquisition, tool use, completion, downloads, sharing and recommendation clicks while keeping telemetry privacy-minimized.
- Preserve the existing Worker, AI, Pages/x2t, renderer and admin-authentication paths.

Cloudflare runtime configuration
- Analytics Engine binding: USAGE_ANALYTICS -> OMTOOLS_USAGE
- CF_ACCOUNT_ID
- ANALYTICS_READ_TOKEN
- ADMIN_DASHBOARD_TOKEN
Secret values are intentionally not stored in source control.

Endpoints
- POST /api/telemetry
  Anonymous first-party events: page_view, heartbeat, tool_open, tool_start, tool_complete, conversion_success, conversion_fail, download, share, related_click, popular_click.
- GET /api/popular-tools
  Public aggregate-only ranking from the most recent 7 days.
  sampleEnough becomes true only when recent tool_open total is at least 10.
  The response never contains anonymous IDs, IPs, user-level records, raw referrers, inputs or file information.
  Cache-Control: public, max-age=60, s-maxage=300.
- GET /api/admin/dashboard
  Requires Authorization: Bearer <ADMIN_DASHBOARD_TOKEN>.
  Existing metrics remain, with toolStarts, toolCompletes, completionRate, shares, relatedClicks, popularClicks and source breakdown added.

Analytics Engine schema
- index1: random anonymous browser ID
- blob1: event
- blob2: page path, query string excluded
- blob3: tool identifier
- blob4: language
- blob5: source category
- blob6: constrained internal event detail
- double1: 1

Source categories
- direct, internal, google, naver, bing, daum, producthunt, reddit, dcinside, share, other
- src=share takes precedence.
- document.referrer is inspected only in the browser to derive a hostname category. The full referrer URL and search terms are not sent to Analytics Engine.

Privacy
- Do not write raw IP addresses, full referrer URLs, query strings, filenames, uploaded files, converted content, free-text tool input or account identifiers to Analytics Engine.
- Share URLs use the canonical tool URL plus only the fixed src=share parameter.

Funnel
page_view -> tool_open -> tool_start -> tool_complete -> download/share/related_click
popular_click is recorded from the home popular-tools area.
tool_start and tool_complete are capped at one each per page lifecycle by the common telemetry client.
