@overvio/woocommerce

WooCommerce integration for Overvio SDK - provides automatic cart tracking, checkout funnel events, coupon tracking, and more.

Installation

npm install @overvio/woocommerce @overvio/sdk
# or
pnpm add @overvio/woocommerce @overvio/sdk

Quick Start

Via CDN (Recommended for WordPress)

Add the following PHP to your theme's functions.php or plugin:

add_action('wp_footer', function() {
  $context = [
    'apiKey' => 'pk_live_your_api_key',
    'user' => is_user_logged_in() ? [
      'id' => get_current_user_id(),
      'email' => wp_get_current_user()->user_email,
      'firstName' => wp_get_current_user()->first_name,
      'lastName' => wp_get_current_user()->last_name,
    ] : null,
    'cart' => WC()->cart ? array_values(array_map(function($item, $key) {
      $product = $item['data'];
      return [
        'key' => $key,
        'product_id' => $item['product_id'],
        'variation_id' => $item['variation_id'] ?? 0,
        'quantity' => $item['quantity'],
        'product_name' => $product->get_name(),
        'product_sku' => $product->get_sku(),
        'line_total' => $item['line_total'],
        'line_subtotal' => $item['line_subtotal'],
        'variation' => $item['variation'] ?? [],
      ];
    }, WC()->cart->get_cart(), array_keys(WC()->cart->get_cart()))) : [],
    'currency' => get_woocommerce_currency(),
    'pageType' => overvio_get_page_type(),
  ];

  echo '<script>window.OvervioContext = ' . json_encode($context) . ';</script>';
  echo '<script src="https://cdn.overvio.ai/v1/woocommerce.min.js" defer></script>';
});

function overvio_get_page_type() {
  if (is_front_page() || is_home()) return 'home';
  if (is_shop()) return 'shop';
  if (is_product()) return 'product';
  if (is_product_category()) return 'product_category';
  if (is_product_tag()) return 'product_tag';
  if (is_cart()) return 'cart';
  if (is_checkout()) return 'checkout';
  if (is_wc_endpoint_url('order-received')) return 'order_received';
  if (is_account_page()) return 'my_account';
  return 'other';
}

Via NPM (for bundled builds)

import { initWooCommerce } from '@overvio/woocommerce';

const sdk = initWooCommerce({
  apiKey: 'pk_live_your_api_key', // Optional if in OvervioContext
  debug: true, // Enable console logging
});

Features

Automatic Tracking

The WooCommerce integration automatically tracks:

• view_cart: When the cart page is loaded
• begin_checkout: When checkout page initializes
• add_shipping_info: When shipping method is selected
• add_payment_info: When payment method is selected
• order_completed: On thank you page (requires PHP setup)
• coupon_applied: When a coupon is successfully applied
• coupon_failed: When coupon application fails
• coupon_removed: When a coupon is removed

Cart Adapter

The cart adapter syncs cart state with WooCommerce:

import { WooCommerceCartAdapter } from '@overvio/woocommerce';

const adapter = new WooCommerceCartAdapter({ debug: true });

// Listen to cart changes
adapter.onChange((items) => {
  console.log('Cart updated:', items.length, 'items');
});

// Set source for next add-to-cart (for tracking context)
adapter.setNextSource('search');

PHP Integration Requirements

Order Tracking (Thank You Page)

To track order completions, add the following to your theme or plugin:

add_action('woocommerce_thankyou', function($order_id) {
  $order = wc_get_order($order_id);
  if (!$order) return;

  $products = [];
  foreach ($order->get_items() as $item) {
    $product = $item->get_product();
    $products[] = [
      'productId' => (string) $product->get_id(),
      'name' => $item->get_name(),
      'quantity' => $item->get_quantity(),
      'price' => (float) ($item->get_total() / $item->get_quantity()),
      'sku' => $product->get_sku(),
      'categories' => wp_list_pluck(
        get_the_terms($product->get_id(), 'product_cat') ?: [],
        'name'
      ),
    ];
  }

  $order_data = [
    'orderId' => (string) $order_id,
    'orderNumber' => $order->get_order_number(),
    'total' => (float) $order->get_total(),
    'subtotal' => (float) $order->get_subtotal(),
    'currency' => $order->get_currency(),
    'products' => $products,
    'coupons' => $order->get_coupon_codes(),
    'discount' => (float) $order->get_total_discount(),
    'shipping' => (float) $order->get_shipping_total(),
    'tax' => (float) $order->get_total_tax(),
    'paymentMethod' => $order->get_payment_method(),
    'customer' => [
      'email' => $order->get_billing_email(),
      'firstName' => $order->get_billing_first_name(),
      'lastName' => $order->get_billing_last_name(),
    ],
    'billingCountry' => $order->get_billing_country(),
    'shippingCountry' => $order->get_shipping_country(),
  ];

  echo '<script>window.OvervioOrderData = ' . json_encode($order_data) . ';</script>';
});

Enhanced Coupon Tracking

For detailed coupon tracking, expose coupon data via PHP:

add_action('wp_footer', function() {
  if (!is_cart() && !is_checkout()) return;

  $coupon_map = [];
  foreach (WC()->cart->get_applied_coupons() as $code) {
    $coupon = new WC_Coupon($code);
    $coupon_map[strtolower($code)] = [
      'code' => $code,
      'type' => $coupon->get_discount_type(),
      'amount' => (float) $coupon->get_amount(),
    ];
  }

  if (!empty($coupon_map)) {
    echo '<script>window.OvervioCouponDataMap = ' . json_encode($coupon_map) . ';</script>';
  }
});

Checkout Events Enhancement

The SDK listens to standard WooCommerce jQuery events for checkout tracking. Ensure your theme triggers these events:

• init_checkout - Fired when checkout page loads
• updated_checkout - Fired when checkout form updates
• applied_coupon - Fired when coupon is applied
• removed_coupon - Fired when coupon is removed

Configuration Options

interface InitWooCommerceOptions {
  /** Override apiKey from context */
  apiKey?: string;

  /** SDK modules to enable (default: ['events', 'cart']) */
  modules?: ('events' | 'cart' | 'search' | 'banners' | 'recommendations')[];

  /** Custom API endpoints */
  endpoints?: {
    api?: string;
    events?: string;
  };

  /** Disable cart adapter (default: false) */
  disableCartAdapter?: boolean;

  /** Disable auto user identification (default: false) */
  disableAutoIdentify?: boolean;

  /** Disable order tracking on thank you page (default: false) */
  disableOrderTracking?: boolean;

  /** Disable page tracking (view_cart) (default: false) */
  disablePageTracking?: boolean;

  /** Disable checkout funnel tracking (default: false) */
  disableCheckoutTracking?: boolean;

  /** Disable coupon tracking (default: false) */
  disableCouponTracking?: boolean;

  /** Enable debug logging (default: false) */
  debug?: boolean;
}

Manual Tracking

Track View Cart (e.g., for cart drawer)

import { trackViewCart } from '@overvio/woocommerce';

// When cart drawer/modal opens
cartDrawer.addEventListener('open', () => {
  trackViewCart(sdk, { debug: true });
});

Track with Custom Source

import { initWooCommerce, WooCommerceCartAdapter } from '@overvio/woocommerce';

const sdk = initWooCommerce();
const adapter = sdk.cart.getManager()?.getAdapter() as WooCommerceCartAdapter;

// Before adding to cart from search results
adapter?.setNextSource('search');
// ... add to cart action

Events Tracked

| Event | Trigger | Required Context | |-------|---------|------------------| | view_cart | Cart page load | pageType: 'cart' | | begin_checkout | Checkout page init | pageType: 'checkout' | | add_shipping_info | Shipping method selected | Checkout page | | add_payment_info | Payment method selected | Checkout page | | order_completed | Thank you page load | OvervioOrderData | | coupon_applied | Coupon applied via jQuery event | Cart/Checkout | | coupon_failed | Coupon AJAX returns error | Cart/Checkout | | coupon_removed | Coupon removed via jQuery event | Cart/Checkout |

TypeScript Types

All types are exported for TypeScript users:

import type {
  InitWooCommerceOptions,
  WooCommerceContext,
  WooCommerceCartItem,
  WooCommerceOrderData,
  WooCommercePageType,
  CartSource,
} from '@overvio/woocommerce';

License

MIT