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

# Naming Events and Attributes in Your Klaritics Integration

> How to name the events and attributes you send to Klaritics, from client SDKs or the External API, and why to avoid the reserved $ prefix.

Consistent event and attribute names make your Klaritics analytics easier to query, chart, and share across your team. This page applies to everything you send, whether through a [client SDK](https://guides.klaritics.com/sdk/overview.md) or the [External API](https://guides.klaritics.com/integrations/external-api.md).

## Name events for what happens in your product

Use clear, descriptive names that map directly to user actions or business events in your app. Pick a casing convention (for example `snake_case` like `add_to_cart`, or `PascalCase` like `ProductClicked`) and use it consistently everywhere you call the SDK.

```js theme={null}
Klaritics.logAppEvent("add_to_cart", {
  userId: "user@example.com",
  value: 1299,
  item: "Sony Head Phone 1201"
});
```

Attach the properties that describe the event: identifiers, amounts, item names, screen names, and any other context you want to slice by later.

> [!NOTE]
>
> The [External API](https://guides.klaritics.com/integrations/external-api.md) **requires** lowercase `snake_case` event names matching `^[a-z][a-z0-9_]*$`, and rejects anything else. If you send events from both SDKs and the API, use `snake_case` everywhere so the same action has the same name in both streams.

## Do not use `$` as a prefix

The Klaritics SDKs use `$` as a reserved prefix for events and attributes that they add on your behalf, such as session events and standard device or user metadata.

> [!WARNING]
>
> Do not use `$` as a prefix for events or attributes that you log. Names you send that start with `$` may collide with the SDK's own data, be filtered out, or behave unpredictably in Klaritics.

Examples:

| Do not use | Use instead |
| - | - |
| `$add_to_cart` | `add_to_cart` |
| `$checkout_completed` | `checkout_completed` |
| `$user_email` | `user_email` |

## Recommended conventions

* Keep names short, lowercase or PascalCase, and consistent across platforms.
* Use verbs for events (`signed_up`, `ProductClicked`) and nouns for attributes (`userId`, `plan`).
* Reuse attribute names across events when they mean the same thing, so charts and funnels line up.
* Document your event taxonomy in one place and share it with everyone integrating a Klaritics SDK. See [Event Taxonomy](https://guides.klaritics.com/data/event-taxonomy.md).

## Summary

* Send events and attributes with plain, descriptive names that match your product.
* Do not use `$` as a prefix for your events or attributes; it is reserved for data added by the Klaritics SDK.
* Keep naming and casing consistent across every platform you integrate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.