Skip to main content

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.

Use this page when you want Cevoid to receive completed purchase events from your storefront. If you are trying to instrument widget, post, or product interactions, use Using Cevoid Galleries or Manual Event Tracking instead. For the exact manual SDK method surface and payload reference, use SDK API and sale.complete.

​
Choose the right sales-tracking path

​
Shopify storefronts

If your storefront runs on Shopify, Cevoid sales tracking is handled through the Shopify checkout web pixel. That means:
  • you do not need @cevoid/analytics-sdk just to track completed sales
  • you do not need to call trackSale() for the standard Shopify setup
  • you should enable the Cevoid checkout web pixel for each Shopify store that should send checkout events
Use the dashboard setup flow for this path. Do not combine the Shopify web-pixel path with manual trackSale() calls for the same storefront. If you run on Shopify, follow the Shopify sales-tracking setup only.

​
Non-Shopify storefronts

If your storefront is not Shopify, use the manual sales-tracking path. That means:
  • initialize Cevoid tracking in your storefront
  • call trackSale() when an order is completed
  • send one completed sale per final order
Use this path only when your storefront is not Shopify.

​
When to use trackSale()

Use trackSale() when both of these are true:
  • your storefront is not Shopify
  • you have a final completed order record to send to Cevoid
Typical trigger points:
  • order confirmation pages
  • checkout success callbacks
  • server-confirmed storefront completion handlers
Do not call trackSale() before the order is actually completed.
For Shopify storefronts, the supported sales-tracking path is the checkout web pixel. Do not add manual trackSale() calls on top of it.

​
Why session tracking usually belongs with sales tracking

Cevoid uses the session layer to measure attribution between Cevoid gallery activity and a completed order. That means:
  • if session tracking is enabled and consent resolves to granted, Cevoid can connect supported gallery interactions and the completed sale through session_id
  • if session tracking is not enabled, the sale can still be recorded, but Cevoid usually cannot connect a Cevoid widget event to that order
In practice, you usually want session tracking enabled when you enable sales tracking.

​
1. Initialize the SDK

import { init } from '@cevoid/analytics-sdk'

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

​
2. Optionally identify the shopper

If you already know the shopper identity, call identify() first so the conversion event can include that context. 
import { identify } from '@cevoid/analytics-sdk'

identify({
  profileId: 'profile_123',
  externalId: 'shopify_customer_456'
})

​
3. Send the completed sale

import { trackSale } from '@cevoid/analytics-sdk'

trackSale({
  orderId: 'order_123',
  marketId: 'market_123',
  customerId: 'cust_456',
  currency: 'USD',
  revenue: 129.99,
  skus: ['SKU-1', 'SKU-2']
})
Required fields:
  • orderId
  • currency
  • revenue
Optional fields:
  • marketId
  • customerId
  • skus
revenue must be sent as a decimal major-unit amount in the same currency as currency, such as 129.99 USD.

​
4. Send one event per completed order

Recommended pattern:
  • choose one stable completion trigger
  • send one conversion event per completed order
  • prevent duplicates on page reload or repeated callbacks
Cevoid also deduplicates completed sales server-side by workspace and orderId, so repeated trackSale() calls for the same order do not create multiple counted sales. You should still do your own best-effort deduplication and avoid sending the same order more than once from the client or server. Avoid sending trackSale() from:
  • cart pages
  • checkout start events
  • optimistic client-side states before payment confirmation

​
5. Verify the sales flow

After setup:
  • complete one real or test order through the path you implemented
  • confirm the order only triggers one completed sale event from your chosen integration path
  • if session tracking is enabled and consent resolves to granted, confirm the sale can include session_id
If you are on Shopify, verify the checkout web pixel path. If you are not on Shopify, verify your manual trackSale() trigger.

​
Session note

Session tracking is optional, but it is usually recommended when you want sales attribution. If session tracking is enabled and consent resolves to granted, trackSale() can include a Cevoid session_id. If consent is denied:
  • the conversion event can still be sent
  • session_id is omitted
If you enable session tracking without sales tracking, Cevoid can still measure how users interact with galleries and cards. That setup is valid when you only need widget analytics and do not need to connect those interactions to completed orders.