@wix/analytics

A type-safe Wix Analytics SDK for tracking events in Wix applications. This package provides a browser-only interface that proxies to the global window.wixAnalytics.trackEvent method with full TypeScript support for all standard Wix Analytics events.

Installation

``bash
npm install @wix/analytics
`

Quick Start

`typescript
import { trackEvent, registerEventListener } from "@wix/analytics";

// Track standard Wix Analytics events with type safety
trackEvent("AddToCart", {
name: "Example Product",
price: 29.99,
currency: "USD",
category: "Electronics",
quantity: 1,
});

// Track events without parameters
trackEvent("CompleteRegistration");

// Track custom events
trackEvent("custom_button_click", {
eventCategory: "user_interaction",
eventAction: "click",
eventLabel: "header_cta",
});

// Register an event listener to monitor analytics events
registerEventListener((eventName, eventData) => {
console.log(Analytics event tracked: ${eventName}, eventData);
});
`

Features

- ✅ Type-safe - Full TypeScript support for all Wix Analytics event types
- ✅ Browser-only - Works in Wix applications where window.wixAnalytics is available
- ✅ Zero dependencies - Lightweight proxy implementation
- ✅ Standard events - Supports all official Wix Analytics events
- ✅ Custom events - Supports custom event tracking with flexible parameters
- ✅ Event monitoring - Register listeners to monitor analytics events as they are tracked

API Reference

$3

Track a Wix Analytics event with type-safe event data.

Parameters:

- eventName - Name of the event to track (supports standard Wix events and custom events)
- eventData - Event data typed according to the event name (optional for some events)

$3

Register an event listener for Wix Analytics events. The listener will be called whenever analytics events are tracked.

Parameters:

- eventHandler - Callback function that will be invoked when analytics events are tracked
- eventName - Name of the tracked event
- eventData - Event data associated with the tracked event

Supported Standard Events

The package provides full TypeScript support for all standard Wix Analytics events:

$3

`typescript
// Add product to cart
trackEvent("AddToCart", {
name: "Product Name",
price: 29.99,
currency: "USD",
category: "Electronics",
quantity: 1,
});

// Track purchase
trackEvent("Purchase", {
id: "order_123",
revenue: 99.99,
contents: [
{
name: "Product 1",
price: 49.99,
quantity: 2,
},
],
});

// Initiate checkout
trackEvent("InitiateCheckout", {
contents: [
{
name: "Product Name",
price: 29.99,
quantity: 1,
},
],
});
`

$3

`typescript
// Click on product
trackEvent("ClickProduct", {
name: "Product Name",
category: "Electronics",
position: "1",
});

// View content
trackEvent("ViewContent", {
name: "Product Name",
category: "Electronics",
price: 29.99,
});

// Lead generation
trackEvent("Lead", {
category: "contact",
action: "form_submit",
});
`

$3

`typescript
// User registration (no parameters needed)
trackEvent("CompleteRegistration");

// Schedule appointment (no parameters needed)
trackEvent("Schedule");
`

$3

`typescript
// Start payment process
trackEvent("StartPayment", {
option: "PayPal",
});

// Add payment info
trackEvent("AddPaymentInfo", {
option: "Visa",
});
`

$3

`typescript
// Custom events with flexible parameters
trackEvent("custom_event_name", {
eventCategory: "user_interaction",
eventAction: "click",
eventLabel: "navigation_menu",
eventValue: 1,
});
`

Event Monitoring

You can register event listeners to monitor analytics events as they are tracked:

`typescript
import { registerEventListener } from "@wix/analytics";

// Register a listener for all analytics events
registerEventListener((eventName, eventData) => {
console.log(Event tracked: ${eventName}, eventData);

// Perform custom logic based on event type
if (eventName === "Purchase") {
console.log("Purchase completed!", eventData);
}
});

// Multiple listeners can be registered
registerEventListener((eventName, eventData) => {
// Send to external analytics service
sendToExternalService(eventName, eventData);
});
`

TypeScript Support

The package exports comprehensive TypeScript types for all events:

`typescript
import type {
WixAnalyticsEventName,
WixAnalyticsEventData,
TrackingParametersAddToCartEvent,
TrackingParametersPurchaseEvent,
TrackingParametersCustomEvent,
} from "@wix/analytics";

// Type-safe event data
const addToCartData: TrackingParametersAddToCartEvent = {
name: "Product Name",
price: 29.99,
currency: "USD",
};

trackEvent("AddToCart", addToCartData);

// Type-safe event listener
registerEventListener((eventName, eventData) => {
// eventName and eventData are fully typed
console.log(Event: ${eventName}, eventData);
});
`

Environment Requirements

This package is designed to work in browser environments only where the Wix Analytics global object is available. It requires:

- Browser environment (not Node.js)
- window.wixAnalytics.trackEvent method to be available

If these requirements are not met, the package will log warnings and gracefully handle the missing dependencies.

Error Handling

The package includes built-in error handling:

- Warns when used in non-browser environments
- Warns when window.wixAnalytics.trackEvent` is not available
- Catches and logs any errors during event tracking

License

MIT