# Installation

> Install and initialize the Cevoid Analytics SDK with a script tag, npm, or React.

Breadcrumb: Analytics SDK › Installation · Updated: 2026-10-17
Docs index: https://docs.cevoid.com/developers/llms.txt

Use this page when you already know you need the Cevoid Analytics SDK and want the supported installation paths. If you are still deciding between automatic gallery behavior, browser-event subscriptions, or manual tracking, start with [Overview](https://docs.cevoid.com/developers/analytics-sdk.md).

## Choose one path

Use the installation path that matches how your storefront is built:

- **Script tag**: fastest setup when you want browser-only initialization and no package imports
- **npm package**: best default when you control storefront application code directly
- **React**: use when your storefront already renders through React

## Script tag

Use the script tag when you want the fastest setup and do not need package imports.

```html
<script
  src="https://cdn.cevoid.com/analytics/v1/script.js"
  data-publishable-key="cev_pk_..."
  data-enable-session-tracking="true"
  data-cookie-domain=".example.com"
></script>
```

Load it as a classic script, without `type="module"`. The script finds its own tag through `document.currentScript`, which is not set for module scripts, so a module script never initializes.

The script reads these `data-*` attributes:

- `data-publishable-key`
- `data-enable-session-tracking`
- `data-cookie-domain`
- `data-api-host`
- `data-emit-browser-events`

After loading, the script auto-initializes and exposes:

- `window.cevoid.init`
- `window.cevoid.reset`
- `window.cevoid.identify`
- `window.cevoid.trackEvent`
- `window.cevoid.trackSale`

Verification:

- open the page after the script loads
- confirm `window.cevoid` exists
- send one test call such as `window.cevoid.trackSale(...)` or listen for a gallery browser event

## npm package

Use the package entry point when you want full control over initialization from your storefront code.

```bash
npm install @cevoid/analytics-sdk
```

```ts
import { init, trackEvent } from '@cevoid/analytics-sdk'

init({
  publishableKey: 'cev_pk_...',
  enableSessionTracking: true,
  cookieDomain: '.example.com'
})

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

Verification:

- confirm your app starts without SDK import errors
- trigger one supported tracking call
- if `emitBrowserEvents` is left on, confirm the matching browser event appears on `window`

## React

Use the React entry point when your storefront already renders through React.

```bash
npm install @cevoid/analytics-sdk
```

```tsx
import { Analytics as CevoidAnalytics, trackEvent } from '@cevoid/analytics-sdk/react'

export function App() {
  return (
    <>
      <CevoidAnalytics publishableKey="cev_pk_..." enableSessionTracking={true} />
      <button
        onClick={() =>
          trackEvent('gallery.upload_cta_click', {
            widgetId: 'gallery-homepage'
          })
        }
      >
        Upload
      </button>
    </>
  )
}
```

Verification:

- mount the `Analytics` component once near your app root
- trigger one supported tracking call from React code
- confirm the event path works before layering in session tracking or consent handling

## Configuration

Call `init()` once before sending events. The React component uses the same props.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `publishableKey` | `string` | None | Required workspace publishable key. |
| `enableSessionTracking` | `boolean` | `false` | Enables Cevoid session tracking after consent checks pass. |
| `cookieDomain` | `string` | None | Sets the domain on the `ca_session` cookie. |
| `emitBrowserEvents` | `boolean` | `true` | Emits browser `CustomEvent`s such as `cevoid:post.click` on `window`. |
| `apiHost` | `string` | `https://telemetry.cevoid.com` | Overrides the telemetry host for development or controlled environments. |

> [!NOTE]
> Repeated `init()` calls after the first successful initialization are ignored.

## Related articles

- [SDK API](https://docs.cevoid.com/developers/analytics-sdk/api.md)
- [Event types](https://docs.cevoid.com/developers/analytics-sdk/events.md)
- [Session tracking](https://docs.cevoid.com/developers/analytics-sdk/setup-session-tracking.md)
- [Consent](https://docs.cevoid.com/developers/analytics-sdk/consent.md)

---

Canonical: https://docs.cevoid.com/developers/analytics-sdk/installation