@cevoid/analytics-sdk

Cevoid's browser-side analytics SDK for storefront integrations.

Use it to initialize client-side tracking, identify shoppers, track Cevoid widget interactions, and send completed purchase events from your storefront.

Installation

npm install @cevoid/analytics-sdk

Quick start

Initialize the SDK once before sending events.

import { identify, init, trackEvent, trackSale } from '@cevoid/analytics-sdk'

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

identify({
  externalId: 'shopify_customer_123'
})

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

trackSale({
  orderId: 'order_123',
  currency: 'USD',
  revenue: 129.99,
  skus: ['SKU-123']
})

Root API

Import from @cevoid/analytics-sdk for browser or storefront integrations.

import { identify, init, reset, trackEvent, trackSale } from '@cevoid/analytics-sdk'

init(config)

Call init() once before your first tracking call.

| Option | Type | Default | Description | | --- | --- | --- | --- | | publishableKey | string | — | Required workspace publishable key. | | enableSessionTracking | boolean | false | Enables Cevoid-managed session tracking after consent checks pass. | | cookieDomain | string | — | Sets the domain for the cevoid_sid cookie. | | emitBrowserEvents | boolean | true | Emits browser CustomEvents such as cevoid:post.click. | | apiHost | string | https://telemetry.cevoid.com | Overrides the telemetry host. |

Repeated calls after the first successful initialization are ignored.

identify(data)

Attaches profile-level context to future events.

Supported fields:

• profileId?: string
• externalId?: string

trackEvent(name, data)

Tracks supported Cevoid UGC widget events.

Use the full event reference for supported event names, payload fields, and accepted values:

• Tracking Events
• Track Events Guide

trackSale(data)

Tracks a completed storefront purchase as sale.complete.

revenue must be provided as a decimal major-unit amount in the same currency as currency, such as 129.99 USD.

Use the full conversion reference and implementation guide here:

• Tracking Events
• Track Conversions Guide

reset()

Clears initialization state, deferred events, and in-memory identity data.

React

Import from @cevoid/analytics-sdk/react for React applications.

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

function App() {
  return (
    <>
      <CevoidAnalytics publishableKey="cev_pk_..." enableSessionTracking={true} />
      <Gallery />
    </>
  )
}

function Gallery() {
  const { trackEvent } = useAnalytics()

  return (
    <button
      type="button"
      onClick={() => {
        trackEvent('gallery.upload_cta_click', {
          widgetId: 'gallery-homepage',
          widgetType: 'gallery'
        })
      }}
    >
      Upload
    </button>
  )
}

Documentation

• Overview
• Installation
• Tracking Events
• Consent
• How It Works
• Track Events Guide
• Track Conversions Guide
• Set Up Session Tracking

Notes

• Initialize the SDK before your first tracking call.
• publishableKey is required for new integrations.
• Session tracking is optional and only needed if you want Cevoid-managed session IDs.