Analytics Event Tracking

OneKey uses a decorator-based logger system to track user behavior events. Events are routed to the analytics server (Mixpanel) via @LogToServer() decorator on scene methods. NEVER call analytics.trackEvent() directly.

Quick Reference

Topic Guide Key Files

Adding events adding-events.md packages/shared/src/logger/scopes/

Architecture architecture.md packages/shared/src/logger/base/

Common pitfalls pitfalls.md —

Critical Rules

• MUST use @LogToServer() decorator — never call analytics.trackEvent() directly

• Event method names use camelCase — the method name becomes the event name sent to Mixpanel

• Methods MUST return params synchronously — never return a Promise

• Deduplicate high-frequency events — prevent Mixpanel usage spikes (e.g., use in-memory Set for per-session dedup)

• Add events to existing scopes when possible — only create new scopes for entirely new feature domains

Adding a Server Event (Quick Steps)

1. Create or update a Scene class

// packages/shared/src/logger/scopes/{scope}/scenes/{scene}.ts import { BaseScene } from '../../../base/baseScene'; import { LogToServer } from '../../../base/decorators';

export class MyScene extends BaseScene { @LogToServer() public myEventName(params: { key: string; value: string }) { return params; } }

2. Register scene in scope index

// packages/shared/src/logger/scopes/{scope}/index.ts import { MyScene } from './scenes/myScene';

export class MyScope extends BaseScope { protected override scopeName = EScopeName.myScope; myScene = this.createScene('myScene', MyScene); }

3. Call from business code

import { defaultLogger } from '@onekeyhq/shared/src/logger/logger';

defaultLogger.myScope.myScene.myEventName({ key: 'foo', value: 'bar' });

Decorator Types

Decorator Destination Use Case

@LogToServer()

Mixpanel analytics server User behavior tracking, business metrics

@LogToLocal()

Device local log (React Native logger) Debugging, device-side diagnostics

@LogToConsole()

Console only Dev-time debugging

Stack decorators for dual logging: @LogToServer()

• @LogToLocal() .

Related Skills

• /1k-architecture — Import hierarchy rules (logger is in @onekeyhq/shared )

• /1k-coding-patterns — TypeScript and React conventions