@wix/analytics

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

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

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)

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

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);

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