add-analytics
Design or add Sesori product analytics. Use when adding a user-facing feature, deciding whether an event is valuable, changing analytics identity/privacy, instrumenting an outcome, or adding BigQuery/Looker metrics. Covers authoritative hook points, layered delivery, bounded event design, GoRouter screen reporting, voice/login exceptions, and warehouse verification.
sesori-ai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add sesori-ai/sesori_apps_monorepo --skill add-analytics技能说明
name: add-analytics description: Design or add Sesori product analytics. Use when adding a user-facing feature, deciding whether an event is valuable, changing analytics identity/privacy, instrumenting an outcome, or adding BigQuery/Looker metrics. Covers authoritative hook points, layered delivery, bounded event design, GoRouter screen reporting, voice/login exceptions, and warehouse verification.
add-analytics
Design analytics that answer a product question without creating misleading or sensitive data.
Before adding an event
An event is worthwhile only when all of these are concrete:
- Decision: What product decision or investor metric changes if this moves?
- Meaning: Is it an intent, confirmed outcome, state transition, or view?
- Authority: Which business success/failure seam proves it happened?
- Population: Is the unit an account, installation, or action? Never mix those denominators under one label.
- Privacy: Can every parameter be a bounded enum/boolean or explicitly approved scalar without code, content, paths, identity, or entity IDs?
- Reporting: Which curated model/view consumes it, and how are coverage, maturity, freshness, and deduplication handled?
If the answer is only “this button was tapped,” skip it unless that tap is the only honest signal for a defined funnel step.
Current and planned seams
The source of truth is the closed models under
client/module_core/lib/src/foundation/models/product_analytics/, with
repository delivery/preference records under repositories/models/ and service
state under services/models/:
- Consumers call
ProductAnalyticsServicefor authenticated account-linked events. - The three approved pre-auth login events call
InstallationAnalyticsService; they are account-less and preference-exempt by explicit product decision. - Delivery flows
Client (Foundation) -> API -> Repository -> Service -> Consumer. Cubits/widgets/listeners never holdAnalyticsClientorAnalyticsApidirectly. - Mobile implements
AnalyticsClientwith Firebase; desktop uses a no-op adapter until desktop analytics has its own approved scope.
Choose the authoritative hook
| Event meaning | Correct seam | Example |
|---|---|---|
| Confirmed outcome | Success branch after repository/service response | Message accepted, session created |
| Failure diagnostic | Explicit typed failure branch | Session creation failed |
| Reactive state | Dedicated listener or bounded transition guard | Bridge/screen state |
| Screen | GoRouterRouteSource -> exhaustive AnalyticsScreen mapping | product_screen_viewed |
| Flutter-only capability | UI call site after capability succeeds, calling Layer-3 service | Voice transcription completed |
| Pre-auth login | LoginCubit terminal state through InstallationAnalyticsService | Timeout by provider |
Never use a widget tap as a proxy when a confirmed outcome exists. Never emit a success event when an operation is queued, merely attempted, or later requeued. Capture product-event occurrence time at that authoritative seam before any preference deferral; a later Firebase emission timestamp must not move funnel or retention timing.
Screen reporting
GoRouterRouteSource.currentRouteStreamis the sole screen source.- Map every
AppRouteDefexhaustively to a pinnedAnalyticsScreen; never send concrete paths, project/session IDs, or Dart enum names as implicit wire values. - Disable Firebase automatic screen reporting on Android and Firebase-enabled Apple targets.
- Emit canonical account-linked
product_screen_viewed, then let the Firebase adapter best-effort mirror the same pinned name throughlogScreenView. - Curated account metrics use only
product_screen_viewed; standardscreen_viewis diagnostic. Test one custom + one native event per changed GoRouter route and no automatic duplicate.
Parameters and naming
- Event/parameter names: pinned
snake_case, max 40 characters. - Use enums for closed values and explicit converters/mappings for existing sealed types. Do not assume a domain type is an enum.
- Max 25 parameters per GA4 event; fewer is better.
- Do not rename a released wire value. Add a schema version when semantics must change.
input_mode=voice_assistedmeans a successful transcript contributed to the submitted composer value; it never means the final text was unedited. Preserve that bounded origin with any restored composer draft.
Identity and privacy
Never report:
- prompt, response, transcript, code, reasoning, or tool content;
- file/repository/project/session/branch/worktree names or paths;
- raw or hashed project/session/bridge/device/notification IDs;
- OAuth identity, username, email, provider user ID, IP/geography, or raw error text;
- coding provider/model/agent/tool/command names unless a later approved plan changes the privacy contract.
Account-linked events use only the pseudonymous custom user_key produced in
the repository. Never set Firebase global user_id for the new design.
Installation login events carry no user_key or attempt ID and may not be
extended beyond their approved provider/failure enums without a new decision.
Implementation checklist
- Add a closed event variant and pinned parameter enums to the active source of truth.
- Identify the authoritative success/failure/transition seam.
- Route through the correct Layer-3 service; update every mobile/desktop constructor consumer in lockstep.
- Keep product behavior independent: analytics is best-effort, failure-isolated, and never changes product success.
- Generate source outputs; never hand-edit generated files.
- Test exact wire names/parameters, success-only emission, failure/no-op paths, deduplication, and absence of sensitive values.
- Add/update versioned BigQuery transforms and fixture
ASSERTs. Account metrics useuser_keyplus the eligible auth snapshot; instal