mirror of
https://github.com/iflytek/skillhub.git
synced 2026-11-16 09:21:18 +00:00
212 lines
13 KiB
Markdown
212 lines
13 KiB
Markdown
# Passive frontend analytics contract
|
|
|
|
<!-- #region analytics-body -->
|
|
For installation, platform initialization, upgrades, shutdown and acceptance, use the
|
|
[Chinese configuration guide][analytics-guide]. It is the authoritative operator
|
|
procedure for runtime Compose and Kubernetes/Helm. This document owns the event,
|
|
module, configuration and privacy contracts; it does not duplicate deployment steps.
|
|
Docker/Compose and Helm ship optional analytics with Web. No configuration means no
|
|
controller/adapter chunk, SDK or collection request. The small configuration gate is
|
|
part of bootstrap; the controller and SDK are not. Business components remain passive.
|
|
|
|
## Contract and scope
|
|
|
|
`data-analytics-id` names an action category, not a unique event, resource or user.
|
|
It describes intent, not its result. IDs match `^[a-z]+(?:\.[a-z]+){2,}$`.
|
|
Lowercase dotted names are independent of language, visible text and layout.
|
|
Published meanings are frozen. A meaning change requires a new ID. Renames/removals
|
|
need release notes and a reviewed [manifest](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-manifest.json) diff.
|
|
The manifest is an AST source inventory, not a runtime closed enum or a count of
|
|
users, pageviews, successful operations or exhaustive business coverage.
|
|
|
|
The inventory includes landing/search, skills, suites, publishing, review,
|
|
governance, namespaces, GitHub integration, notifications, preferences, account,
|
|
authentication, administration and navigation. Literal branches distinguish finite
|
|
actions. Never interpolate resource, slug, version, user, provider, role or backend
|
|
values into IDs. Fixed navigation metadata is source-owned. Forwarding sites do
|
|
not necessarily represent DOM elements; portals and repeated resources share IDs.
|
|
|
|
Run from the repository root with dependencies already installed:
|
|
|
|
```sh
|
|
node web/scripts/analytics-manifest.mjs
|
|
# Only after reviewing intentional source changes:
|
|
node web/scripts/analytics-manifest.mjs --write
|
|
pnpm -C web test src/app/analytics-manifest.test.ts src/features/analytics
|
|
```
|
|
|
|
### Original eight compatibility meanings
|
|
|
|
| ID | Meaning |
|
|
| --- | --- |
|
|
| search.query.submit | Native search form submission, not typing or search success. |
|
|
| skill.card.open | Existing card click or direct Enter/Space activation. |
|
|
| skill.detail.render | Structural loaded detail root, not an automatic pageview. |
|
|
| skill.download.request | Download attempt; guards may reject it. |
|
|
| skill.command.copy | Command-copy attempt, not clipboard or installation success. |
|
|
| skill.prompt.copy | Prompt-copy attempt, not execution or installation success. |
|
|
| skill.publish.request | Publish/update/resubmit attempt, not avatar-only save. |
|
|
| skill.publish.confirm | Explicit publish warning continuation, not every dialog. |
|
|
|
|
Installation-method tabs distinguish SkillHub and ClawHub without changing the
|
|
original command-copy meaning. Visibility choices and business modes use static
|
|
categories, not data fetched from the selected object.
|
|
|
|
## Native observation policy and limits
|
|
|
|
Attributes alone do not create events. Keep one nearest semantic target per event.
|
|
Never change defaults, propagation, focus, history, permissions or app handlers.
|
|
|
|
- FORM uses submit, not submit-button click plus submit. Enter converges here;
|
|
rejected native validation may produce no submit. Typing/clear is not submission.
|
|
- Ordinary buttons/links use click, including browser-generated keyboard click.
|
|
Ignore disabled, aria-disabled and data-disabled controls. App guards still apply.
|
|
- DIV role=link cards with existing Enter/Space handlers also use keydown. Do not
|
|
synthesize activation. Ignore repeat, IME and modifier keydown. Native buttons
|
|
must not count keydown and their generated click twice.
|
|
- Tabs generate click from navigation keys; do not count Arrow/Home/End again.
|
|
Do not invent keyboard support for existing mouse-only rows/directories.
|
|
- Native selects, checkboxes and radio changes have different boundaries. An
|
|
option marker can describe static selection intent, never its value/text. Do
|
|
not infer committed selection from opening a trigger or highlighting an item.
|
|
- Radix selection may use pointerup or Enter/Space in a portal. Trigger typeahead
|
|
can change selection without opening an item. Trigger interaction is not proof
|
|
of committed selection; never capture typed keys. Current finite rules do not
|
|
implement select/file/drop/crop; do not misconfigure them as click.
|
|
- File selection and dropping only offer files, not upload success. Do not read
|
|
filename/path/metadata. Programmatic picker clicks are not extra user actions;
|
|
cancellation is not observed. Crop interaction is not proof of changed pixels.
|
|
- Explicit cancel/close retains workflow meaning. Escape, overlay, route teardown,
|
|
browser Back, automatic close and native picker cancel are not reliably observed
|
|
by these markers. Closing is not proof a pending request was aborted.
|
|
|
|
Use document delegation for portals; React ancestry is not DOM ancestry. Wrappers
|
|
forward caller-scoped IDs, not guessed business IDs. Reject nested unmarked
|
|
interactive controls rather than attributing them to an ancestor card/form.
|
|
Synthetic temporary download anchors do not prove new successful user actions.
|
|
SPA classification, consent transitions and view deduplication are separate
|
|
policies; never derive them from full URLs/query strings.
|
|
|
|
## Single product source and interfaces
|
|
|
|
The sole helper is `web/src/features/analytics/skillhub-intents.mjs`:
|
|
|
|
- `observeSkillhubIntents({ root, rules, onIntent }) -> stop`.
|
|
- Frozen `DEFAULT_RULES` has the original twelve rules listed in the guide.
|
|
- `resolveRules(rules) -> { active, skipped: [{ id, reason }] }` is pure. Invalid
|
|
containers produce id:null and no active rules. Unknown IDs are not rejected
|
|
merely for being absent from the manifest. Invalid grammar/types are skipped.
|
|
- Omitted rules use defaults. Explicit rules replace defaults; {} collects nothing.
|
|
- click excludes FORM/SELECT/TEXTAREA/non-button INPUT; submit is FORM-only; card
|
|
is DIV role=link only. Host validity is checked at observation, not resolution.
|
|
- Intent is exactly `{ id, event }`; event is click/submit/keydown. Same-version
|
|
evolution is additive optional allowlisted static fields; consumers ignore
|
|
unknown keys. Breaking changes need a new module contract.
|
|
- Importing does nothing; without callback no listeners are installed. Same root
|
|
returns the same stop and retains the FIRST rules/callback. Stop then initialize
|
|
to change configuration. Old disposers cannot remove a new installation. Stop
|
|
is idempotent; nested observers share event deduplication.
|
|
- Callback throws/rejections are swallowed without affecting business events.
|
|
The helper itself has no network, cookies, storage, identity or history hooks.
|
|
|
|
The controller owns authorization, rule resolution, generations and lifecycle.
|
|
Static registry metadata validates public adapterConfig; factories lazily import
|
|
adapters. Factory cancellation prevents late imports from creating an SDK after
|
|
stop. Adapter exposes `send(intent) -> Promise<void>` (never rejects) and stop().
|
|
The loader runs separately after the first React DOM commit, never blocking mount.
|
|
Disabled, absent, invalid or denied configuration does not import the controller.
|
|
Public `window.skillhubAnalytics.start()` explicitly grants current-page consent;
|
|
stop() immediately disables observation. Enabled=false cannot be overridden by
|
|
start. Deployment changes require recreating Web (`docker compose restart` does not
|
|
re-read the env file); old tabs do not update.
|
|
|
|
## Configuration and proxy
|
|
|
|
`SKILLHUB_WEB_ANALYTICS_CONFIG` is JSON with enabled (boolean/default false),
|
|
adapter (static registry name), consent (denied/granted/default denied), rules
|
|
(optional finite rule map), adapterConfig (adapter-owned public object). Umami
|
|
accepts only websiteId UUID. DataFinder accepts only appId (integer 1..2147483647)
|
|
and optional product (`^[a-z][a-z0-9_]{0,31}$`, default skillhub). No App Key or other
|
|
adapter fields are accepted. Invalid configuration disables only analytics with
|
|
field-only diagnostics, never raw values. Rule resolution keeps its skip behavior.
|
|
The startup parser limits JSON to 64 KiB/32 levels and rejects duplicate keys.
|
|
|
|
`SKILLHUB_WEB_ANALYTICS_UPSTREAM` is a deploy-only HTTP(S) origin: no credentials,
|
|
path, query, fragment, whitespace or injection characters. It is never put in
|
|
browser configuration. Existing BusyBox tools validate deployment control fields;
|
|
base64 transports JSON safely as data into the existing no-store runtime-config.js.
|
|
No jq, Node runtime, extra package, CSP relaxation or HTML injection is required.
|
|
|
|
The reserved same-origin prefix is `/_skillhub-analytics/`. BASE_PATH is applied in
|
|
the browser; existing Nginx rewrite strips it once. Enabled configurations generate
|
|
exact script.js and api/send routes for Umami, or one POST-only list route for
|
|
DataFinder, with method restrictions; all other paths are
|
|
404, never a platform administration endpoint. Consent-denied enabled configurations retain those routes
|
|
for explicit dynamic start, but do not load/request them automatically.
|
|
Variable proxy_pass uses the existing resolver at request time. HTTPS verifies
|
|
certificates using the system trust bundle and correct SNI. Collector proxying
|
|
strips Cookie/Authorization/Referer and hides Set-Cookie. API/auth routes, 100M
|
|
uploads, TLS, business caching and permissions are not changed.
|
|
|
|
## Privacy and integration modes
|
|
|
|
Allowlist static id/event and adapter-owned fields described below, not text/HTML, input/option values, clipboard,
|
|
URLs/query/fragment, cookies, account identities, codes/tokens, private paths,
|
|
filenames, review reasons or crop data. Test IDs can contain resource identifiers;
|
|
do not scrape them. The manifest is not a payload.
|
|
|
|
Umami 3.4.1 uses manual-only script attributes and a final before-send sanitizer.
|
|
Only `{type:'event',payload:{website,name,data:{event}}}` survives; website must
|
|
match configuration, name must match product grammar and Umami's 50-character
|
|
limit. Pageview/identify/performance/context/extra data are dropped. Payload values
|
|
are read once. A non-enumerable toJSON guard rechecks stop synchronously at fetch
|
|
dispatch; upgrading the SDK must reverify its ordering with dispatch-boundary tests.
|
|
Stop cannot recall a fetch already started.
|
|
|
|
At most 20 valid intents wait in memory for up to three seconds while the SDK
|
|
loads. Excess, failure, timeout or stop drops them. Once ready, requests are
|
|
independent and time-bounded, with no retry/durable queue/post-load backlog.
|
|
Do not load a second Umami tracker. Missing/blocked/offline collectors never reject
|
|
into the application. SDK loading is trusted code with page privileges: review and
|
|
pin its version, access and retention; it is not an arbitrary remote-JS plugin.
|
|
|
|
This is NOT anonymous transport. IP/User-Agent/Origin still reach the platform.
|
|
The SDK sends website, actual hostname and session cache headers, reads
|
|
URL/title/referrer before sanitization, and reads its own localStorage switch.
|
|
Nginx strips sensitive headers before the collector, not before the browser's
|
|
request reaches Web. Web logs require their own privacy policy. Umami can derive
|
|
browser/OS/device/geo/session from transport metadata. With pinned 3.4.1 absent URL
|
|
stores empty path/query and fallback hostname localhost; title/referrer/screen/
|
|
language/distinct identity remain absent. Removing JSON fields does not disable
|
|
transport-derived processing. Operators must review consent, logs, access and law.
|
|
|
|
DataFinder sends the minimal `/list` JSON array directly through same-origin fetch
|
|
with keepalive, credentials omitted and no referrer. No official SDK is shipped,
|
|
proxied or loaded. One intent is one batch, without batching delay or event storage;
|
|
fetch and response parsing share a three-second deadline, no retries. Acceptance
|
|
requires HTTP success, e=0 and sc=1, not HTTP 200 alone. Failures are best-effort drops.
|
|
Events retain their dotted ID; params is the JSON string `{ "event": "click" }`
|
|
(or submit/keydown). header.custom contains only product and module. The optional
|
|
generic context getter is passed from bootstrap through loader/controller/factory;
|
|
it is read at send time. Bootstrap uses the already-loaded app router's matched
|
|
route metadata (routesById[routeId].fullPath), never concrete match paths, params,
|
|
query or hash. Unmatched routes use other. Analytics does not eagerly import the router.
|
|
|
|
DataFinder's user_unique_id and web_id share an anonymous random UUID v4 (crypto.randomUUID,
|
|
or crypto.getRandomValues where randomUUID is unavailable, e.g. plain-HTTP origins) stored
|
|
under localStorage key `skillhub.analytics.datafinder.browser-id`. Invalid stored
|
|
values are replaced. Unavailable storage falls back to one in-memory ID for the
|
|
page, including stop/start. This enables per-browser UV and is not linked to the
|
|
SkillHub account. Deployers must decide whether this persistent identifier is
|
|
acceptable. Disabled/denied collection does not run this code or access the key.
|
|
Only the identifier persists, never events. Clearing the key rotates a stored ID.
|
|
IP/User-Agent/Origin remain transport metadata; the proxy preserves browser UA.
|
|
No App Key is accepted in browser settings or sent by this adapter.
|
|
|
|
Supported-platform deployment, initialization, verification, upgrade, shutdown and
|
|
custom adapter development are documented in the guide. Custom adapters require
|
|
reviewed code, registry validation, cancellation, final payload cleaning and exact
|
|
proxy routes; business components must remain vendor-neutral and passive.
|
|
<!-- #endregion analytics-body -->
|
|
|
|
[analytics-guide]: frontend-analytics-integration.md
|