> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saytics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Design and Send Custom Events in Saytics

> Custom events let you track actions specific to your product. Learn how to name events, structure properties, and build a consistent event schema.

Custom events are the events you define to track actions that matter to your product beyond standard page views. While Saytics auto-tracks page views when `autoPageview` is enabled, custom events capture the specific user behaviors — feature usage, conversions, lifecycle milestones — that reflect how people actually get value from your product.

## Event taxonomy

An event taxonomy is a consistent naming convention applied to every event you track. Establishing one early prevents the common problem of having duplicate or ambiguous events — for example, `purchase`, `purchase_complete`, `order_placed`, and `checkout_success` all describing the same action. A well-defined taxonomy makes your data easier to query, share across teams, and maintain as your product grows.

## Naming convention

Saytics recommends the **"\<Object> \<Action>"** pattern in title case. The object is the thing being acted on; the action is what happened to it.

* "Report Exported" — not "export" or "exportReport"
* "Team Member Invited" — not "invite" or "team\_invite\_sent"
* "Subscription Upgraded" — not "upgrade\_sub" or "subscriptionUpgraded"

Here are examples of good and bad event names:

| Good                      | Bad                   | Why                     |
| ------------------------- | --------------------- | ----------------------- |
| `"Report Exported"`       | `"export"`            | Descriptive, title case |
| `"Subscription Upgraded"` | `"upgrade_sub"`       | Clear object + action   |
| `"Comment Posted"`        | `"new_comment_event"` | No suffix needed        |

## Common event categories

Most products track events that fall into three broad categories. Expand each one to see recommended event names and a code example.

<AccordionGroup>
  <Accordion title="Onboarding events">
    Onboarding events track a user's progress through initial setup and activation. Use them to measure where users drop off before reaching their first meaningful action.

    Recommended events: `"Account Created"`, `"Profile Completed"`, `"First Event Tracked"`

    ```js theme={null}
    // Fired immediately after the account is created
    Saytics.track('Account Created', {
      signup_method: 'google',
      plan: 'trial'
    });

    // Fired when the user finishes filling out their profile
    Saytics.track('Profile Completed', {
      fields_filled: 5
    });

    // Fired when the user sends their first tracking event
    Saytics.track('First Event Tracked', {
      event_name: 'Button Clicked',
      source: 'javascript_sdk'
    });
    ```
  </Accordion>

  <Accordion title="Engagement events">
    Engagement events track how users interact with key features after onboarding. Use them to identify your most-used functionality and understand which behaviors correlate with retention.

    Recommended events: `"Feature Used"`, `"Dashboard Viewed"`, `"Report Exported"`

    ```js theme={null}
    // Fired when a user interacts with a named feature
    Saytics.track('Feature Used', {
      feature: 'cohort_analysis',
      location: 'sidebar'
    });

    // Fired when a user views their analytics dashboard
    Saytics.track('Dashboard Viewed', {
      dashboard_id: 'dash_001',
      chart_count: 4
    });

    // Fired when a user exports a report
    Saytics.track('Report Exported', {
      format: 'csv',
      row_count: 1200
    });
    ```
  </Accordion>

  <Accordion title="Lifecycle events">
    Lifecycle events track changes to a user's relationship with your product — starting a subscription, ending a trial, or closing their account. Use them to measure revenue events and churn signals.

    Recommended events: `"Subscription Started"`, `"Trial Ended"`, `"Account Deleted"`

    ```js theme={null}
    // Fired when a user activates a paid subscription
    Saytics.track('Subscription Started', {
      plan: 'pro',
      mrr: 49.99,
      billing_cycle: 'monthly'
    });

    // Fired when a trial period ends (converted or expired)
    Saytics.track('Trial Ended', {
      converted: true,
      trial_length_days: 14
    });

    // Fired when a user deletes their account
    Saytics.track('Account Deleted', {
      reason: 'too_expensive',
      tenure_days: 90
    });
    ```
  </Accordion>
</AccordionGroup>

## Event volume and limits

<Info>
  Saytics supports up to 1,000 unique event names per workspace. Plan your taxonomy early to avoid hitting this limit as your product grows.
</Info>

If you're approaching the limit, audit your events for duplicates or overly granular names that can be consolidated. For example, separate events like `"CSV Downloaded"`, `"PDF Downloaded"`, and `"Excel Downloaded"` can often be replaced with a single `"Report Exported"` event that includes a `format` property.

## Testing your events

After adding tracking calls to your app, verify they're arriving correctly using the Live Feed in the Saytics dashboard. Navigate to **Events → Live Feed** to see a real-time stream of incoming events, including their properties and the user or anonymous ID they're attributed to.

Trigger the action in your app, then check the Live Feed to confirm:

* The event name matches what you defined
* All expected properties are present with the correct values
* The event is attributed to the right user or session

If an event doesn't appear within a few seconds, check that the SDK is initialized and that no console errors are present. Enabling `debug: true` in `Saytics.init` will log all SDK activity to the browser console during development.