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

# Track User Actions and Events Using Cano Analytics

> Learn how to track user actions as events in Cano Analytics, from naming conventions to batch sending and viewing your real-time event stream.

Events are the foundation of Cano Analytics — every user action you capture becomes a queryable, visualizable data point. Whether a visitor views a page, clicks a button, or completes a purchase, each of those moments is an event you can analyze, filter, and chart in your Cano dashboard.

## What Is an Event?

Every event you send to Cano Analytics is made up of four parts:

| Field        | Type                | Description                                   |
| ------------ | ------------------- | --------------------------------------------- |
| `name`       | string              | What happened (e.g. `purchase_completed`)     |
| `properties` | key-value map       | Context about the event (e.g. plan, amount)   |
| `timestamp`  | ISO 8601 datetime   | When the event occurred (auto-set if omitted) |
| `user_id`    | string *(optional)* | The user who performed the action             |

## Event Naming Conventions

Use **snake\_case** and **past tense** for all event names. This keeps your event data consistent and readable across everyone who uses your Cano dashboards.

Good examples:

* `user_signed_up`
* `page_viewed`
* `purchase_completed`
* `button_clicked`
* `subscription_cancelled`

Avoid generic names like `click` or `event1` — specific names make your dashboards far easier to understand at a glance.

## Tracking Events

Call `cano.track()` with an event name and an optional properties object. The SDK automatically attaches a timestamp and any previously set super properties.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Track a page view with referrer context
  cano.track('page_viewed', {
    page: '/pricing',
    referrer: 'google'
  });

  // Track a button interaction
  cano.track('button_clicked', {
    button: 'upgrade_cta',
    location: 'header'
  });

  // Track a completed purchase
  cano.track('purchase_completed', {
    plan: 'pro',
    amount: 49,
    currency: 'USD'
  });
  ```

  ```python Python theme={null}
  from cano_analytics import CanoClient

  client = CanoClient(api_key="YOUR_API_KEY")

  # Track a page view with referrer context
  client.track(
      event='page_viewed',
      properties={
          'page': '/pricing',
          'referrer': 'google'
      }
  )

  # Track a button interaction
  client.track(
      event='button_clicked',
      properties={
          'button': 'upgrade_cta',
          'location': 'header'
      }
  )

  # Track a completed purchase
  client.track(
      event='purchase_completed',
      properties={
          'plan': 'pro',
          'amount': 49,
          'currency': 'USD'
      }
  )
  ```
</CodeGroup>

## Tracking Page Views

Use `cano.page()` to record when a user visits a page or screen. Unlike `track()`, `cano.page()` is specifically designed for navigation events — it automatically captures the page URL, title, and referrer so you don't have to pass them manually.

```javascript JavaScript theme={null}
// Track the current page — URL, title, and referrer are captured automatically
cano.page();

// Optionally pass a name and extra properties
cano.page('Pricing', {
  section: 'plans',
  experiment: 'annual_toggle_v2'
});
```

Call `cano.page()` on every route change in single-page apps (SPAs) — automatic page-view detection is not included in the SDK, so you need to call it manually on each navigation event.

## Server-Side vs. Client-Side Tracking

Both approaches send the same event structure to Cano — the difference is where the call originates.

<Tabs>
  <Tab title="Client-Side (Browser / Mobile)">
    Use the JavaScript SDK to track events directly from the user's device. This is ideal for UI interactions like button clicks, page views, and form submissions where you need low-latency capture.

    **Best for:** page views, UI interactions, front-end funnels

    ```javascript JavaScript theme={null}
    // Runs in the user's browser
    cano.track('page_viewed', { page: '/dashboard' });
    ```
  </Tab>

  <Tab title="Server-Side (Backend)">
    Use the Python SDK or the REST API to track events from your own servers. This gives you full control over the data and is harder to block or tamper with.

    **Best for:** revenue events, subscription changes, backend workflows

    <CodeGroup>
      ```python Python theme={null}
      # Runs on your server — trusted and tamper-proof
      client.track(
          user_id='usr_123',
          event='purchase_completed',
          properties={'plan': 'pro', 'amount': 49, 'currency': 'USD'}
      )
      ```

      ```bash REST API theme={null}
      curl -X POST https://api.canoanalytics.io/v1/events \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "user_id": "usr_123",
          "event": "purchase_completed",
          "properties": {
            "plan": "pro",
            "amount": 49,
            "currency": "USD"
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Tip>
  Always track revenue and subscription events server-side. Client-side calls can be blocked by ad blockers or manipulated by users, which leads to inaccurate revenue data in your dashboards.
</Tip>

## Batch Tracking

When you need to send many events at once — for example, during a backfill or a high-throughput pipeline — use `cano.batch()` instead of making individual `track()` calls. Batching reduces HTTP overhead and is the recommended approach for server-side pipelines.

<CodeGroup>
  ```javascript JavaScript theme={null}
  cano.batch([
    {
      event: 'page_viewed',
      user_id: 'usr_123',
      properties: { page: '/home' }
    },
    {
      event: 'button_clicked',
      user_id: 'usr_123',
      properties: { button: 'upgrade_cta', location: 'header' }
    },
    {
      event: 'purchase_completed',
      user_id: 'usr_123',
      properties: { plan: 'pro', amount: 49, currency: 'USD' }
    }
  ]);
  ```

  ```python Python theme={null}
  client.batch([
      {
          'event': 'page_viewed',
          'user_id': 'usr_123',
          'properties': {'page': '/home'}
      },
      {
          'event': 'button_clicked',
          'user_id': 'usr_123',
          'properties': {'button': 'upgrade_cta', 'location': 'header'}
      },
      {
          'event': 'purchase_completed',
          'user_id': 'usr_123',
          'properties': {'plan': 'pro', 'amount': 49, 'currency': 'USD'}
      }
  ])
  ```
</CodeGroup>

The batch endpoint accepts up to **500 events per request**. Larger payloads should be split into multiple batch calls.

## Viewing Tracked Events

Once events arrive, open your [Cano dashboard](https://app.canoanalytics.io) and navigate to the **Events** tab. You'll see a real-time stream of incoming events with their properties, timestamps, and associated user IDs. Use the search bar to filter by event name or property value, and click any event row to inspect its full payload.

Events typically appear in the stream within **1–2 seconds** of being sent.

## Next Steps

<CardGroup cols={2}>
  <Card title="Identify Users" icon="user" href="/docs/tracking/identify-users">
    Link your events to real user profiles so you can analyze behavior by person, segment, and cohort.
  </Card>

  <Card title="Custom Properties" icon="tag" href="/docs/tracking/custom-properties">
    Attach rich context to events and users with typed properties that are queryable in every chart.
  </Card>
</CardGroup>