Hamster Analytics Patterns
Quick Reference
| Task |
Pattern |
Reference |
| Track server event (NestJS) |
trackServerEvent('Event Name', props, userId) |
server-tracking.md |
| Track client event |
createAnalyticsTracker(analytics, context) |
client-tracking.md |
| Set account context |
analytics.setAccountId(accountId) |
group-analytics.md |
| Update user properties |
identifyServerUser(userId, traits) |
user-traits.md |
| Mark feature adoption |
UserTraitManager.markFeatureAdoption(userId, 'feature') |
user-traits.md |
| Increment engagement |
UserTraitManager.incrementEngagementCounter(userId, 'counter', count) |
user-traits.md |
When to Apply
- Adding event tracking to new features
- Implementing user property updates
- Adding feature adoption flags or engagement counters
- Working with Mixpanel Group Analytics (account_id)
- Implementing session replay privacy controls
Architecture Overview
Dual-mode system:
- Server-side (NestJS):
trackServerEvent() with SEGMENT_WRITE_KEY
- Client-side (Browser/Server Actions):
createAnalyticsTracker() with NEXT_PUBLIC_SEGMENT_WRITE_KEY
┌─────────────────────────────────────────────────────────────────┐
│ Analytics Architecture │
├─────────────────────────────────────────────────────────────────┤
│ NestJS Services/API → trackServerEvent() → Segment │
│ Next.js Server Actions → createAnalyticsTracker() → Segment │
│ Client Components → createAnalyticsTracker() → Segment │
│ ↓ │
│ Mixpanel │
│ (+ Session │
│ Replay) │
└─────────────────────────────────────────────────────────────────┘
Critical Rules
- Always include
account_id - Required for Mixpanel Group Analytics
- Use snake_case for property names:
account_id, user_id, brief_id
- Use Title Case for event names:
'Brief Created', 'Task Completed'
- Never block operations - Wrap analytics in try-catch
- Add feature adoption - New features need
has_used_* flag + engagement counter
Key Patterns
Server-Side Tracking (NestJS)
import { trackServerEvent } from '@kit/analytics';
trackServerEvent(
'Task Created',
{
task_id: task.id,
brief_id: briefId,
account_id: accountId, // REQUIRED for Group Analytics
user_id: userId,
creation_method: 'ai_generated',
},
userId,
);
Client/Server Action Tracking
import { analytics, createAnalyticsTracker } from '@kit/analytics';
const tracker = createAnalyticsTracker(analytics, {
user_id: user.id,
account_id: accountId,
});
await tracker.trackBriefCreated({
brief_id: brief.id,
account_id: accountId,
has_initial_content: true,
});
New Feature Checklist
When adding a new user-facing feature:
References
- server-tracking.md - NestJS/API tracking patterns
- client-tracking.md - Client and server action tracking
- group-analytics.md - Mixpanel Group Analytics (account_id)
- session-replay.md - Mixpanel Session Replay privacy
- user-traits.md - Feature adoption and engagement counters
- event-catalog.md - Event dictionary and user properties
Key Files
| File |
Purpose |
packages/analytics/src/event-types.ts |
Event dictionary with TypeScript types |
packages/analytics/src/user-properties.ts |
User trait definitions and enums |
packages/analytics/src/user-trait-manager.ts |
Feature adoption and engagement |
packages/analytics/src/server-analytics.ts |
Server-side tracking functions |
packages/analytics/src/tracking-utils.ts |
AnalyticsTracker class |
1---2name: hamster-analytics3description: "Analytics tracking patterns for Segment, Mixpanel, and user engagement metrics. Use when implementing event tracking, user properties, or engagement counters."4version: "1.1.0"5metadata:6 source: https://skillmd.com/skills/gethamster/hamster-analytics7---89# Hamster Analytics Patterns1011## Quick Reference1213| Task | Pattern | Reference |14| --- | --- | --- |15| Track server event (NestJS) | `trackServerEvent('Event Name', props, userId)` | [server-tracking.md](references/server-tracking.md) |16| Track client event | `createAnalyticsTracker(analytics, context)` | [client-tracking.md](references/client-tracking.md) |17| Set account context | `analytics.setAccountId(accountId)` | [group-analytics.md](references/group-analytics.md) |18| Update user properties | `identifyServerUser(userId, traits)` | [user-traits.md](references/user-traits.md) |19| Mark feature adoption | `UserTraitManager.markFeatureAdoption(userId, 'feature')` | [user-traits.md](references/user-traits.md) |20| Increment engagement | `UserTraitManager.incrementEngagementCounter(userId, 'counter', count)` | [user-traits.md](references/user-traits.md) |2122## When to Apply2324- Adding event tracking to new features25- Implementing user property updates26- Adding feature adoption flags or engagement counters27- Working with Mixpanel Group Analytics (account_id)28- Implementing session replay privacy controls2930## Architecture Overview3132**Dual-mode system:**33341. **Server-side** (NestJS): `trackServerEvent()` with `SEGMENT_WRITE_KEY`352. **Client-side** (Browser/Server Actions): `createAnalyticsTracker()` with `NEXT_PUBLIC_SEGMENT_WRITE_KEY`3637```38┌─────────────────────────────────────────────────────────────────┐39│ Analytics Architecture │40├─────────────────────────────────────────────────────────────────┤41│ NestJS Services/API → trackServerEvent() → Segment │42│ Next.js Server Actions → createAnalyticsTracker() → Segment │43│ Client Components → createAnalyticsTracker() → Segment │44│ ↓ │45│ Mixpanel │46│ (+ Session │47│ Replay) │48└─────────────────────────────────────────────────────────────────┘49```5051## Critical Rules52531. **Always include `account_id`** - Required for Mixpanel Group Analytics542. **Use snake_case** for property names: `account_id`, `user_id`, `brief_id`553. **Use Title Case** for event names: `'Brief Created'`, `'Task Completed'`564. **Never block operations** - Wrap analytics in try-catch575. **Add feature adoption** - New features need `has_used_*` flag + engagement counter5859## Key Patterns6061### Server-Side Tracking (NestJS)6263```typescript64import { trackServerEvent } from '@kit/analytics';6566trackServerEvent(67 'Task Created',68 {69 task_id: task.id,70 brief_id: briefId,71 account_id: accountId, // REQUIRED for Group Analytics72 user_id: userId,73 creation_method: 'ai_generated',74 },75 userId,76);77```7879### Client/Server Action Tracking8081```typescript82import { analytics, createAnalyticsTracker } from '@kit/analytics';8384const tracker = createAnalyticsTracker(analytics, {85 user_id: user.id,86 account_id: accountId,87});8889await tracker.trackBriefCreated({90 brief_id: brief.id,91 account_id: accountId,92 has_initial_content: true,93});94```9596### New Feature Checklist9798When adding a new user-facing feature:99100- [ ] Add tracking event with `account_id`101- [ ] Add `has_used_feature` boolean to UserProperties102- [ ] Add `feature_usage_count` number to UserProperties103- [ ] Add to `markFeatureAdoption()` union type104- [ ] Add to `incrementEngagementCounter()` union type105- [ ] Implement first-time detection106- [ ] Track milestone event with `time_since_signup_hours`107108## References109110- [server-tracking.md](references/server-tracking.md) - NestJS/API tracking patterns111- [client-tracking.md](references/client-tracking.md) - Client and server action tracking112- [group-analytics.md](references/group-analytics.md) - Mixpanel Group Analytics (account_id)113- [session-replay.md](references/session-replay.md) - Mixpanel Session Replay privacy114- [user-traits.md](references/user-traits.md) - Feature adoption and engagement counters115- [event-catalog.md](references/event-catalog.md) - Event dictionary and user properties116117## Key Files118119| File | Purpose |120| --- | --- |121| `packages/analytics/src/event-types.ts` | Event dictionary with TypeScript types |122| `packages/analytics/src/user-properties.ts` | User trait definitions and enums |123| `packages/analytics/src/user-trait-manager.ts` | Feature adoption and engagement |124| `packages/analytics/src/server-analytics.ts` | Server-side tracking functions |125| `packages/analytics/src/tracking-utils.ts` | AnalyticsTracker class |