Analytics Spec

Metrics Definition

This page is the authoritative source for backend analytics calculations used in Dashboard, Traffic Analysis, App Analytics, and Channel reports.

Purpose

Use one metric contract across teams. Product, QA, ops, and marketing should validate numbers against this document when reconciling data.

Data Sources

Table: analytics

Web events, app telemetry, and API-level download redirects.

Table: orders

License purchases and order status data.

Table: paddle_events

Raw Paddle webhook processing records.

Event Time

All backend filters use unix timestamp range. Daily trend labels use Asia/Shanghai (UTC+8).

Core Funnel Metrics

Metric	Definition	Source Events
Homepage	Total homepage page views where `event_type='page_view'` and `meta.url IN ('/', '/index.html')`.	`page_view`
Download	Distinct download actors from API redirects plus direct binary clicks. API downloads use `api_download_latest`. Direct clicks are `click_download` where file ends `.exe` or `.deb`.	`api_download_latest`, `click_download`
Checkout	Distinct session IDs across explicit checkout events and checkout/pricing page views.	`view_checkout`, `view_pricing`, `click_buy`, checkout/pricing `page_view`
Purchased	Count of orders in selected window with active status.	`orders.status='active'`

Download Attribution Rules

Preferred signal is backend redirect event api_download_latest.
Fallback/extra signal is direct binary click from web telemetry (click_download with binary file extension).
Source attribution comes from meta.source, fallback to meta.utm_source, then unknown.
Historical backfill uses nginx access logs and writes normalized api_download_latest rows.

App Analytics: Feature Mapping

Feature Usage Heatmap is not limited to manual feature tags. It maps core app behavior to unified labels:

app_feature_used                -> feature value from meta.feature
app_scan_complete               -> scan_complete
app_scan_performance            -> scan_performance
app_scan_error/auth_error       -> scan_error
app_test_connection_error       -> test_connection_error
app_cleanup                     -> cleanup_action
app_view_tab                    -> view_tab:<tab_name>
app_trial_started               -> trial_started
app_license_active              -> license_activated
app_trial_upgrade_cta_click     -> trial_upgrade_click
app_trial_upgrade_checkout_open -> trial_upgrade_checkout_open

Paddle Transaction Metric

“Completed Transactions” in admin summary counts both transaction.completed and transaction.paid to match current webhook setup and avoid undercount when completed is delayed or missing.

Reconciliation Notes

Traffic Analysis and Funnel can differ because one uses broad event logs while funnel applies step-specific filters.
Session-based metrics and IP-based metrics are intentionally different. Session count does not equal unique visitors.
Ad blockers, offline clients, or DNS/proxy failures can still reduce web event completeness.

Change Control

Any metric logic change must update this page in the same release. Treat this file as a release-gated contract, not optional documentation.

Metrics

See the metrics in a live scan instead of reading them in isolation.

Save your first $1,000 before the next billing cycle.

Download Trial View Pricing