# Feedback Component Activity Data

This document details all data captured by the Feedback component, including current implementation and recommended additions for enhanced analytics, AI agent context, and support prioritization.

## Current Data Capture

### FeedbackData (Root Object)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `sentiment` | `Sentiment` | User selection | Yes | 5-point scale: very-dissatisfied, dissatisfied, neutral, satisfied, very-satisfied | Sentiment analysis, NPS correlation, priority routing |
| `message` | `string` | User input | No | Free-text feedback content | AI analysis, keyword extraction, support ticket creation |
| `user` | `FeedbackUser` | Props (app-provided) | No | User attribution data | Customer identification, history correlation |
| `context` | `Record<string, unknown>` | Props (app-provided) | No | App-specific context (conversationId, featureName, etc.) | Feature-specific analytics, reproduction context |
| `metadata` | `FeedbackMetadata` | Auto-captured | No | Browser/session metadata | Technical debugging, UX analysis |

### FeedbackUser

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `id` | `string` | App auth system | No | Unique user identifier | Customer lookup, feedback history aggregation |
| `email` | `string` | App auth system | No | User email address | Direct follow-up, support ticket creation |
| `name` | `string` | App auth system | No | Display name | Personalized responses, support context |

### FeedbackMetadata

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `url` | `string` | `window.location.href` | Yes | Full page URL at submission | Feature/page correlation, deep linking |
| `timestamp` | `string` | `new Date().toISOString()` | Yes | ISO-8601 submission time | Time-based analysis, response SLA tracking |
| `viewport` | `{ width, height }` | `window.innerWidth/Height` | Yes | Browser viewport dimensions | Responsive design debugging, UX analysis |
| `userAgent` | `string` | `navigator.userAgent` | Yes | Browser/OS identification string | Platform-specific issues, compatibility tracking |

---

## Recommended Additional Fields

### Customer Status (High Priority)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `customer.plan` | `string` | App billing system | No | Subscription tier (free, starter, pro, enterprise) | Priority routing, churn prediction, VIP handling |
| `customer.isPayingCustomer` | `boolean` | App billing system | No | Whether user is on paid plan | Support prioritization, revenue impact analysis |
| `customer.accountAgeMs` | `number` | App auth system | No | Milliseconds since account creation | Onboarding friction analysis, lifecycle stage |
| `customer.mrr` | `number` | App billing system | No | Monthly recurring revenue (cents) | Revenue-weighted prioritization |
| `customer.teamSize` | `number` | App org system | No | Number of users in customer's org | Account importance, expansion opportunity |

### Session Context (High Priority)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `session.id` | `string` | Session storage | No | Unique session identifier | Session replay correlation, journey analysis |
| `session.startedAt` | `string` | Session storage | No | ISO timestamp when session began | Session duration calculation |
| `session.durationMs` | `number` | Computed | No | Time from session start to feedback | Frustration detection (quick rage feedback) |
| `session.pageViewCount` | `number` | Session storage | No | Pages viewed in current session | User journey complexity |
| `session.currentPageDurationMs` | `number` | Page-level tracking | No | Time spent on current page before feedback | Page-specific friction detection |
| `session.previousPages` | `string[]` | Session storage | No | Last N page paths in session (e.g., last 5) | Journey reconstruction, pattern detection |

### Device & Environment (Medium Priority)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `device.type` | `'mobile' \| 'tablet' \| 'desktop'` | Computed from viewport/UA | No | Device category | Platform-specific issue routing |
| `device.isTouchDevice` | `boolean` | `'ontouchstart' in window` | No | Touch capability | Mobile UX issue detection |
| `device.pixelRatio` | `number` | `window.devicePixelRatio` | No | Display density | High-DPI rendering issues |
| `device.language` | `string` | `navigator.language` | No | Browser language setting | Localization issues, regional routing |
| `device.timezone` | `string` | `Intl.DateTimeFormat().resolvedOptions().timeZone` | No | User timezone | Time-aware support, regional patterns |
| `device.connectionType` | `string` | `navigator.connection?.effectiveType` | No | Network quality (4g, 3g, 2g, slow-2g) | Performance-related feedback correlation |

### Referrer & Campaign (Medium Priority)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `acquisition.referrer` | `string` | `document.referrer` | No | Referring URL | Traffic source correlation |
| `acquisition.utmSource` | `string` | URL params | No | UTM source parameter | Campaign attribution |
| `acquisition.utmMedium` | `string` | URL params | No | UTM medium parameter | Channel attribution |
| `acquisition.utmCampaign` | `string` | URL params | No | UTM campaign parameter | Campaign-specific feedback |
| `acquisition.landingPage` | `string` | Session storage | No | First page URL in session | Entry point analysis |

### Feedback History (Medium Priority)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `history.feedbackCountLast30d` | `number` | Backend/localStorage | No | Feedback submissions in last 30 days | Frequent feedback detection, engagement level |
| `history.lastFeedbackAt` | `string` | Backend/localStorage | No | ISO timestamp of last feedback | Recency analysis |
| `history.avgSentimentLast30d` | `number` | Backend | No | Average sentiment score (1-5) | Trend detection, at-risk identification |
| `history.hasOpenTicket` | `boolean` | Support system | No | Whether user has unresolved support ticket | Context for support team |

### Feature Usage Context (Lower Priority)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `usage.featuresUsedThisSession` | `string[]` | App tracking | No | Features/actions used in session | Feature-specific feedback correlation |
| `usage.lastActionBeforeFeedback` | `string` | App tracking | No | Most recent user action | Trigger identification |
| `usage.errorCountThisSession` | `number` | Error tracking | No | Errors encountered in session | Frustration correlation |
| `usage.lastErrorMessage` | `string` | Error tracking | No | Most recent error text | Issue identification |

### Performance Context (Lower Priority)

| Field | Type | Source | Required | Description | Use Case |
|-------|------|--------|----------|-------------|----------|
| `performance.pageLoadTimeMs` | `number` | Performance API | No | Current page load duration | Performance-related feedback |
| `performance.memoryUsageMb` | `number` | `performance.memory` | No | JS heap size | Memory leak correlation |
| `performance.longTaskCount` | `number` | Performance Observer | No | Long tasks (>50ms) on current page | UI jank correlation |

---

## AI Agent Use Cases

### Support Prioritization Agent

An AI agent can use this data to automatically prioritize and route feedback:

1. **Priority Score Calculation**: Combine `customer.mrr`, `customer.plan`, `sentiment`, and `session.durationMs` to compute urgency
2. **Churn Risk Detection**: Flag patterns like declining sentiment over `history.avgSentimentLast30d` combined with high `customer.mrr`
3. **VIP Routing**: Automatically escalate enterprise customers with negative sentiment to dedicated support

### Context Understanding Agent

When responding to or analyzing feedback, an AI agent benefits from:

1. **Journey Reconstruction**: Use `session.previousPages` and `usage.lastActionBeforeFeedback` to understand what led to the feedback
2. **Technical Context**: Combine `device.*`, `performance.*`, and `metadata.userAgent` to identify platform-specific issues
3. **Feature Attribution**: Use `context` and `url` to map feedback to specific product areas

### Proactive Outreach Agent

Identify customers who need attention before they churn:

1. **Frustration Signals**: Short `session.durationMs` + negative sentiment + `usage.errorCountThisSession > 0`
2. **Power User Feedback**: High `history.feedbackCountLast30d` indicates engaged users worth retaining
3. **New User Friction**: Low `customer.accountAgeMs` + negative sentiment = onboarding issues

### Analytics Aggregation

Aggregate feedback for product insights:

1. **Feature Health Dashboard**: Group by `context.featureName` and track sentiment trends
2. **Platform Comparison**: Compare sentiment across `device.type` to identify platform-specific UX issues
3. **Campaign Effectiveness**: Correlate `acquisition.utmCampaign` with early user sentiment

---

## Implementation Notes

### Privacy Considerations

- All customer-identifying fields should respect user consent preferences
- Consider anonymization for aggregate analytics
- Sensitive fields like `customer.mrr` should only be captured server-side

### Performance Impact

- Session tracking should use efficient storage (sessionStorage vs repeated API calls)
- Performance metrics should be sampled, not captured on every submission
- Consider lazy-loading heavy computations (device detection, performance metrics)

### Data Volume

- Consider which fields to capture client-side vs enrich server-side
- High-cardinality fields (session.previousPages) should be capped
- Archive/aggregate historical data to prevent storage bloat