@builtonveya/analytics-web

Veya Analytics SDK for the web. Auto-detects page types, product impressions and cart changes on restaurant ordering sites, and ships events to the Veya analytics pipeline in batches.

Shares its core with @builtonveya/analytics-react-native (same event taxonomy, same version line).

Install

npm / yarn / pnpm

npm install @builtonveya/analytics-web

import veya from '@builtonveya/analytics-web';

await veya.init({ tenantSlug: 'your-tenant-slug' });

Script tag (the package ships a self-contained browser bundle that sets window.veya)

<script src="https://cdn.jsdelivr.net/npm/@builtonveya/analytics-web@4/dist/veya-analytics.min.js"></script>
<script>
  veya.init({ tenantSlug: 'your-tenant-slug' });
</script>

Pin the major (@4) for automatic patch updates, or an exact version (@4.0.0) for a frozen build.

Configure

await veya.init({
  tenantSlug: 'your-tenant-slug',      // required
  endpoint: 'https://analytics.builtonveya.com/v1/events',   // the default
  storeId: 'store-81',                 // if known at init; otherwise call veya.setStore(id, name)
  debug: false,
  autoDetect: true,                    // page-type detection on navigation
  autoTrackProducts: true,             // product impressions
  autoTrackCart: true,                 // cart change detection
  interceptOloApi: false,              // opt-in: patches window.fetch to read Olo order responses
  batchSize: 10,
  flushInterval: 5000,
  sessionTimeout: 1800000,             // 30 minutes
});

Track

Everything the core SDK offers is on the default export: track, pageView, productView, productClick, addToCart, removeFromCart, updateCartQuantity, setCart, checkoutStart, checkoutStep, addPaymentInfo, checkoutComplete, loginAttempt, loginSuccess, loginFailure, logout, identify, storeSelect, setStore, search, loyaltyLogin, rewardView, rewardApply, rewardRemove, promoApply, promoRemove, setExperiment, error, flush, getSessionId, getVisitorId, getCustomerId.

veya.setStore('81', 'Earthbar Flagship - West Hollywood');
veya.addToCart({ id: 'olo:item:106702642', name: 'The Workout Smoothie', price: 12.95 }, 1);
veya.checkoutComplete({ order_id: '46749…', total: 12.95, items: [...] });

init() can be called more than once: calls made while one is in flight share it, and later calls resolve straight away, so React StrictMode's double effects are harmless.

Automatic events

Properties named exactly email, phone, password, ssn, credit_card, cvv, address or street are dropped from every event (and from identify() traits) as a backstop against sending personal data by mistake. Only those exact top-level keys: don't rely on it to catch delivery_address, streetAddress or nested objects. ZIP / postal codes are allowed: send address_postal_code (5-digit ZIP) for delivery-area analysis, never the street address.

Changes in 4.0.4

• Calling identify(), loginSuccess(), logout() or setExperiment() before init() no longer stores an empty session id, and a stored session without an id is never resumed. Before, every event in such a session was rejected for a missing session_id. Their effect on login state and experiments survives only when init() starts a new session, so still call them after await veya.init().

Changes in 4.0.3

• The PII backstop no longer drops postal_code and zip — only the street-level address and street (plus the existing email / phone / password / SSN / card / CVV keys). A ZIP is coarse enough to keep, and it's what delivery-area analysis runs on; 4.0.2 dropped it along with the street address.

Changes in 4.0.2

• page_unload is sent on pagehide instead of beforeunload. A beforeunload listener keeps Firefox from putting the page in its back/forward cache, so Back reloaded the page instead of restoring it; pagehide doesn't, and mobile browsers fire it more reliably when a tab is closed. New property persisted: true when the page went into the back/forward cache rather than unloading.
• A page restored from the back/forward cache restarts time_on_page and the scroll_depth thresholds, and sends a page_view when autoDetect is on. Before, time_on_page after Back counted from the original load and scroll depth never fired again.
• The PII backstop also drops address, street, postal_code and zip (4.0.3 keeps the ZIP keys again). query is deliberately not on the list: search events use it for what was typed.
• Removed the aiEndpoint and useAiClassification options: nothing read them, and aiEndpoint defaulted to a host that doesn't resolve. TypeScript code that still passes them gets an excess-property error; delete them.

Changes in 4.0.1

• session_start is sent (it was dropped because init() tracked it before marking itself initialized), once per new session.
• No automatic page_view with autoDetect: false — 4.0.0 sent one on every load in addition to the app's own.
• New automatic events: page_hidden / page_visible and scroll_depth (see above).
• New method: addPaymentInfo(paymentMethod, properties?) → add_payment_info with { payment_method } at funnel step checkout_payment (4).
• Unloading the page sends page_unload instead of session_end (the session carries on across full navigations).
• Defaults: endpoint is the live https://analytics.builtonveya.com/v1/events (4.0.0 pointed at a host that doesn't resolve); interceptOloApi is now opt-in.
• Concurrent init() calls share one run instead of both setting up listeners and sending session_start.

Server-side rendering

Importing the package on the server is safe: module load only registers window.veya when a window exists, and nothing touches the DOM until init() runs. Call init() from a client-side effect.

Build & publish

cd sdk/web
npm ci
npm run build      # dist/esm (ESM + types), dist/cjs, dist/veya-analytics[.min].js
npm run smoke      # loads all three outputs and checks the public surface
npm publish        # prepublishOnly runs build + smoke; scope @builtonveya is public

Bump version in package.json in step with the React Native package when the shared core changes.