@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

npm install @wix/analytics

Quick Start

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

trackEvent(eventName, eventData?)

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)

registerEventListener(eventHandler)

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:

E-commerce Events

// 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,
    },
  ],
});

User Interaction Events

// 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",
});

Registration and Conversion Events

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

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

Payment Events

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

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

Custom Events

// 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:

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:

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<WixAnalyticsEventName>((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