# Product Analytics Event Taxonomy

Use this template before instrumentation starts. The goal is to make events understandable to product, engineering, growth, and support.

## 1. Measurement Brief

- Product or feature:
- Primary user:
- Business goal:
- User outcome:
- Primary funnel:
- Activation definition:
- Retention definition:
- Reporting owner:
- Instrumentation owner:
- Review date:

## 2. Naming Rules

- Use past-tense event names for completed user actions.
- Prefer `object_action` names such as `project_created`, `checkout_started`, or `invite_sent`.
- Avoid vague names such as `button_clicked` unless the button itself is the product behavior.
- Use consistent object names across events.
- Keep property names lowercase with underscores.
- Separate user actions from system events.
- Keep marketing attribution properties separate from product behavior properties.

## 3. Core Event Table

| Event name | Trigger | User intent | Required properties | Optional properties | Owner | Priority |
| --- | --- | --- | --- | --- | --- | --- |
| `signup_started` | User opens or submits the first signup step | Start account creation | `source`, `entry_point` | `campaign`, `device_type` | Product | High |
| `signup_completed` | Account is created successfully | Finish account creation | `user_id`, `plan`, `source` | `company_size`, `role` | Product | High |
| `onboarding_step_completed` | User completes an onboarding step | Move toward first value | `step_name`, `step_index` | `time_on_step` | Product | High |
| `integration_connected` | User connects an external service | Enable workflow value | `integration_name`, `connection_type` | `error_count` | Engineering | High |
| `first_value_reached` | User completes the activation milestone | Receive first meaningful outcome | `activation_path`, `time_to_value` | `template_used` | Product | High |
| `invite_sent` | User invites another teammate | Expand usage | `invitee_role`, `workspace_id` | `invite_method` | Growth | Medium |
| `upgrade_started` | User enters upgrade flow | Evaluate paid plan | `current_plan`, `target_plan` | `source_page` | Growth | High |
| `upgrade_completed` | Payment or plan upgrade succeeds | Become paid customer | `target_plan`, `billing_period` | `coupon_code` | Growth | High |
| `feature_used` | User uses the core feature | Execute recurring workflow | `feature_name`, `workspace_id` | `duration`, `output_count` | Product | Medium |
| `error_encountered` | User-visible error appears | Blocked or interrupted | `error_code`, `surface`, `severity` | `retry_available` | Engineering | High |

## 4. Shared Properties

| Property | Type | Applies to | Notes |
| --- | --- | --- | --- |
| `user_id` | string | All authenticated events | Avoid email in analytics tools unless explicitly approved. |
| `workspace_id` | string | Team products | Useful for B2B account-level reporting. |
| `role` | string | Signup, onboarding, activation | Product role, not company title unless needed. |
| `plan` | string | Billing and entitlement events | Normalize values across systems. |
| `source` | string | Entry and conversion events | Organic, paid, referral, internal, direct. |
| `entry_point` | string | Signup and onboarding | Page, modal, campaign, invite, marketplace. |
| `device_type` | string | All events | Mobile, tablet, desktop. |
| `experiment_id` | string | Experimented flows | Only when an experiment applies. |

## 5. Funnel Definition

| Step | Event | Success signal | Common drop-off reason | Follow-up question |
| --- | --- | --- | --- | --- |
| 1 | `signup_started` | Visitor begins account creation | Weak offer, unclear CTA, form friction | Is the value obvious before the form? |
| 2 | `signup_completed` | Account exists | Verification or password friction | Are users abandoning at authentication? |
| 3 | `onboarding_step_completed` | User progresses through setup | Too many required decisions | Can defaults reduce effort? |
| 4 | `integration_connected` | Required external service connected | Permissions or trust issue | Is the integration ask explained? |
| 5 | `first_value_reached` | User gets useful output | Setup did not produce value | What is the shortest path to value? |
| 6 | `feature_used` | User repeats core behavior | Value was one-time or unclear | What creates a habit loop? |
| 7 | `upgrade_completed` | User pays | Pricing or plan confusion | What proof is missing before upgrade? |

## 6. QA Checklist

- [ ] Every high-priority event has a precise trigger.
- [ ] Event names follow one naming convention.
- [ ] Required properties are feasible to capture at trigger time.
- [ ] No sensitive personal data is sent unnecessarily.
- [ ] Events are tested in development and production.
- [ ] Dashboard definitions match event definitions.
- [ ] Product and engineering agree on activation and conversion definitions.