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

# Manual Event Tracking

> Use trackEvent() when you need to send Cevoid widget interaction events manually from custom storefront code.

Use this page when you need to call [`trackEvent()`](../analytics-sdk/api#trackeventname-data) yourself from custom storefront code. If you are using standard Cevoid galleries or cards, do not start here. Those widget surfaces already emit the core Cevoid UGC events automatically.

For payload-by-payload reference, use [SDK API](../analytics-sdk/api) and [Event Types](../analytics-sdk/events/index).

## When to use [`trackEvent()`](../analytics-sdk/api#trackeventname-data)

Use [`trackEvent()`](../analytics-sdk/api#trackeventname-data) when:

* you render Cevoid interactions in your own storefront UI
* you need to manually mirror Cevoid widget-style actions from custom code
* you want those custom interactions to follow the supported Cevoid event names

Do not use [`trackEvent()`](../analytics-sdk/api#trackeventname-data) just to forward standard gallery or card events into GA or GTM. In that case, use [Forward Browser Events to GA](./forward-events-to-ga).

## 1. Initialize the SDK

Initialize the SDK once before the first tracking call.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { init } from '@cevoid/analytics-sdk'

init({
  publishableKey: 'cev_pk_...'
})
```

React example:

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Analytics as CevoidAnalytics } from '@cevoid/analytics-sdk/react'

export function App() {
  return <CevoidAnalytics publishableKey="cev_pk_..." />
}
```

Verification:

* trigger one manual call in the browser
* confirm your handler runs without an initialization error
* if browser events are enabled, confirm a matching `cevoid:<event-name>` [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) fires on `window`

## 2. Send supported event names

Send the exact dotted Cevoid event name that matches the UI action.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { trackEvent } from '@cevoid/analytics-sdk'

trackEvent('widget.load', {
  widgetId: 'gallery-homepage',
  widgetType: 'gallery',
  postsLoadedCount: 12
})

trackEvent('post.click', {
  widgetId: 'gallery-homepage',
  widgetType: 'gallery',
  postId: 'post_123',
  postPosition: 1
})
```

Common manual event groups:

* widget lifecycle: [`widget.load`](../analytics-sdk/events/widget-load), [`widget.view`](../analytics-sdk/events/widget-view)
* post interactions: [`post.view`](../analytics-sdk/events/post-view), [`post.click`](../analytics-sdk/events/post-click), [`post.view.popup`](../analytics-sdk/events/post-view-popup), [`post.clap`](../analytics-sdk/events/post-clap)
* product interactions: [`product.click.tag`](../analytics-sdk/events/product-click-tag), [`product.click.post`](../analytics-sdk/events/product-click-post), [`product.click.card`](../analytics-sdk/events/product-click-card)
* gallery actions: [`gallery.load_more`](../analytics-sdk/events/gallery-load-more), [`gallery.upload_cta_click`](../analytics-sdk/events/gallery-upload-cta-click)

## 3. Use real Cevoid IDs

Pass the real Cevoid identifiers from the rendered experience:

* `widgetId`
* `postId`
* `productId`
* `marketId` when relevant

Do not substitute labels, DOM IDs, or storefront-only identifiers unless they are the actual Cevoid IDs used by your integration.

## 4. Keep payload details in the reference pages

Use the reference pages for accepted values and field requirements:

* [SDK API](../analytics-sdk/api)
* [Event Types](../analytics-sdk/events/index)

## Common mistakes

* calling [`trackEvent()`](../analytics-sdk/api#trackeventname-data) before `init()`
* using manual tracking for standard Cevoid galleries or cards when the events are already emitted automatically
* using the wrong event name for the actual UI surface
* omitting required Cevoid IDs

## Related

* [Using Cevoid Galleries](./using-cevoid-galleries)
* [Forward Browser Events to GA](./forward-events-to-ga)
* [SDK API](../analytics-sdk/api)
* [Event Types](../analytics-sdk/events/index)