# Custom Events (/docs/events/custom)





# Custom Events [#custom-events]

While Ucoder Insight automatically tracks page views and standard clicks, **Custom Events** allow you to track specific business actions like "Add to Cart", "Form Submission", or "Video Play".

## Config Custom event [#config-custom-event]

```jsx
import { trackCustomEvent } from "ucoder-insight";
```

***

## Data Structure [#data-structure]

Every custom event follows a strict structure to ensure data consistency in your dashboard.

### `trackCustomEvent({dataKey: dataValue})` [#trackcustomeventdatakey-datavalue]

<div className="w-full max-w-[85vw] sm:max-w-full overflow-x-hidden">
  | Property             | Type                     | Required | Description                                                  |
  | :------------------- | :----------------------- | :------- | :----------------------------------------------------------- |
  | **event\_name**      | `string`                 | Yes      | The primary name of the event (e.g., `user_signup`).         |
  | **action\_category** | `string`                 | Yes      | Group similar events (e.g., `ecommerce`, `auth`, `video`).   |
  | **object\_id**       | `string`                 | No       | ID of the object being interacted with (e.g., `product_id`). |
  | **status**           | `'success' \| 'failure'` | No       | Outcome of the action.                                       |
  | **message**          | `string`                 | No       | Readable description or error message.                       |
  | **additionalData**   | `object`                 | No       | Key-value pairs for extra context.                           |
</div>

***

## Usage Examples [#usage-examples]

<Tabs items="['React / Next.js', 'Vanilla JS']">
  <Tab value="React / Next.js">
    ### Blog [#blog]

    ```tsx title="React"
    import { trackCustomEvent } from "ucoder-insight";

    export default function AddToCartButton() {
      trackCustomEvent({
        event_name: "email_input_clicked",
        action_category: "interaction",
        object_id: "email_input_field",
        status: "success",
      });

      return <button onClick={handleAddToCart}>Buy Now</button>;
    }
    ```
  </Tab>

  <Tab value="Vanilla JS">
    ### Form Submission Tracking [#form-submission-tracking]

    ```javascript title="Vanilla JS"
    document.getElementById("signup-form").addEventListener("submit", function(e) {
      window.Ucoder.track("form_submit", {
        action_category: "auth",
        status: "success",
        message: "New user registration",
        additionalData: {
          method: "email",
          referral_source: "google_ads",
          plan_type: "premium"
        }
      });
    });
    ```
  </Tab>
</Tabs>

***

## Data Constraints [#data-constraints]

To maintain performance, `additionalData` only accepts **flat objects**. Nested objects or arrays are not allowed.

Allowed types:

* `string`
* `number`
* `boolean`
* `null` / `undefined`

**Invalid Example:**

<div className="w-full max-w-[85vw] sm:max-w-full overflow-x-hidden">
  ```javascript
  additionalData: {
    user_info: { name: "John" } // ❌ Nested objects are NOT allowed
  }
  ```
</div>