Skip to content

πŸ“ˆ Open source, privacy-first web analytics β€” a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

WooCommerce integration

Blue Mouse96abc7030775
diff --git a/docs/docs/integrations/woocommerce.md b/docs/docs/integrations/woocommerce.md
new file mode 100644
index 000000000..568d17ea7
--- /dev/null
+++ b/docs/docs/integrations/woocommerce.md
@@ -0,0 +1,222 @@
+---
+title: WooCommerce
+slug: /woocommerce-integration
+---
+
+Integrate Swetrix with your WooCommerce store to track page views, monitor user behaviour, and capture key e-commerce events like product views, add-to-cart actions, checkout starts, and purchases.
+
+## Prerequisites
+
+Before adding e-commerce event tracking, make sure the Swetrix tracking script is already installed on your WordPress site. Follow the [WordPress integration guide](/wordpress-integration) to set that up first.
+
+You'll also need access to your child theme's `functions.php` file or a custom site-specific plugin. All of the PHP snippets below should be placed there.
+
+:::caution
+Do **not** edit your parent theme's `functions.php` directly β€” those changes will be lost when the theme updates. Always use a [child theme](https://developer.wordpress.org/themes/advanced-topics/child-themes/) or a simple custom plugin.
+:::
+
+## Check your installation
+
+After installing the base tracking script via the WordPress guide, visit your store and browse a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.
+
+## Tracking e-commerce events
+
+Beyond basic page views, you can track key e-commerce interactions as custom events. The snippets below use WooCommerce action hooks to output small `<script>` blocks that call Swetrix's `swetrix.track()` function with contextual metadata.
+
+You can view these events and their metadata in the **Custom events** section of your Swetrix dashboard. Refer to the [tracking script reference](/swetrix-js-reference) for full API details.
+
+:::tip
+Always **back up your site** before editing theme files. If you're not comfortable editing PHP, consider working with a WordPress developer.
+:::
+
+### 1. Product viewed
+
+Track when a visitor views a single product page. Add the following to your child theme's `functions.php`:
+
+```php
+add_action('woocommerce_after_single_product_summary', 'swetrix_track_product_viewed');
+function swetrix_track_product_viewed() {
+ if (!is_product()) return;
+
+ global $product;
+ if (!$product instanceof WC_Product) return;
+
+ $data = array(
+ 'name' => $product->get_name(),
+ 'sku' => $product->get_sku() ?: strval($product->get_id()),
+ 'price' => strval((float) $product->get_price()),
+ 'currency' => get_woocommerce_currency(),
+ );
+ ?>
+ <script>
+ document.addEventListener('DOMContentLoaded', function () {
+ if (typeof swetrix !== 'undefined') {
+ swetrix.track({
+ ev: 'product_viewed',
+ meta: <?php echo wp_json_encode($data); ?>
+ });
+ }
+ });
+ </script>
+ <?php
+}
+```
+
+### 2. Added to cart
+
+Track when a customer adds a product to their cart from the single product page.
+
+```php
+add_action('woocommerce_after_add_to_cart_button', 'swetrix_track_add_to_cart');
+function swetrix_track_add_to_cart() {
+ global $product;
+ if (!$product instanceof WC_Product) return;
+
+ $data = array(
+ 'name' => $product->get_name(),
+ 'sku' => $product->get_sku() ?: strval($product->get_id()),
+ 'price' => strval((float) $product->get_price()),
+ 'currency' => get_woocommerce_currency(),
+ );
+ ?>
+ <script>
+ document.addEventListener('DOMContentLoaded', function () {
+ var form = document.querySelector('form.cart');
+ if (!form || typeof swetrix === 'undefined') return;
+
+ form.addEventListener('submit', function () {
+ var qtyInput = form.querySelector('input.qty');
+ var qty = qtyInput ? parseInt(qtyInput.value, 10) || 1 : 1;
+
+ var meta = <?php echo wp_json_encode($data); ?>;
+ meta.quantity = String(qty);
+
+ swetrix.track({ ev: 'added_to_cart', meta: meta });
+ });
+ });
+ </script>
+ <?php
+}
+```
+
+Many WooCommerce themes also support AJAX add-to-cart on archive / shop pages (the "Add to Cart" button adds the item without a full page reload). To capture those events, add this separate snippet:
+
+```php
+add_action('wp_footer', 'swetrix_track_ajax_add_to_cart');
+function swetrix_track_ajax_add_to_cart() {
+ if (is_admin()) return;
+ ?>
+ <script>
+ jQuery(document.body).on('added_to_cart', function (e, fragments, hash, $btn) {
+ if (typeof swetrix === 'undefined' || !$btn || !$btn.length) return;
+
+ swetrix.track({
+ ev: 'added_to_cart',
+ meta: {
+ product_id: String($btn.data('product_id')),
+ quantity: String($btn.data('quantity') || 1),
+ source: 'ajax'
+ }
+ });
+ });
+ </script>
+ <?php
+}
+```
+
+:::note
+The AJAX listener above sends limited product details because full product data isn't readily available client-side on archive pages. If you need richer metadata (name, price, SKU), you can output it as `data-*` attributes on the add-to-cart button using the `woocommerce_loop_add_to_cart_link` filter, then read those attributes in the JavaScript handler.
+:::
+
+### 3. Checkout started
+
+Track when a customer reaches the checkout page.
+
+```php
+add_action('woocommerce_before_checkout_form', 'swetrix_track_checkout_started', 5);
+function swetrix_track_checkout_started() {
+ if (is_admin() || !is_checkout()) return;
+
+ $cart = WC()->cart;
+ if (!$cart) return;
+
+ $data = array(
+ 'currency' => get_woocommerce_currency(),
+ 'total' => strval((float) $cart->get_total('edit')),
+ 'item_count' => strval($cart->get_cart_contents_count()),
+ );
+ ?>
+ <script>
+ document.addEventListener('DOMContentLoaded', function () {
+ if (typeof swetrix !== 'undefined') {
+ swetrix.track({
+ ev: 'checkout_started',
+ meta: <?php echo wp_json_encode($data); ?>
+ });
+ }
+ });
+ </script>
+ <?php
+}
+```
+
+### 4. Purchase completed
+
+Track confirmed purchases on the WooCommerce "Thank you" (order received) page.
+
+```php
+add_action('woocommerce_thankyou', 'swetrix_track_purchase', 10, 1);
+function swetrix_track_purchase($order_id) {
+ if (!$order_id) return;
+
+ $order = wc_get_order($order_id);
+ if (!$order || $order->get_meta('_swetrix_tracked')) return;
+
+ $items = array();
+ foreach ($order->get_items() as $item) {
+ $product = $item->get_product();
+ $items[] = $product
+ ? ($product->get_sku() ?: strval($product->get_id())) . ' x' . $item->get_quantity()
+ : strval($item->get_product_id()) . ' x' . $item->get_quantity();
+ }
+
+ $data = array(
+ 'order_id' => strval($order->get_order_number()),
+ 'total' => strval((float) $order->get_total()),
+ 'tax' => strval((float) $order->get_total_tax()),
+ 'shipping' => strval((float) $order->get_shipping_total()),
+ 'currency' => $order->get_currency(),
+ 'items' => implode(', ', $items),
+ );
+
+ $order->update_meta_data('_swetrix_tracked', '1');
+ $order->save();
+ ?>
+ <script>
+ document.addEventListener('DOMContentLoaded', function () {
+ if (typeof swetrix !== 'undefined') {
+ swetrix.track({
+ ev: 'purchase',
+ meta: <?php echo wp_json_encode($data); ?>
+ });
+ }
+ });
+ </script>
+ <?php
+}
+```
+
+The `_swetrix_tracked` order meta flag ensures the purchase event only fires once, preventing duplicate tracking if the customer refreshes the thank-you page.
+
+:::note
+The `meta` field accepts up to 20 keys and a combined value length of 1000 characters. Because of this limit, individual item details are condensed into a single `items` string (e.g. `SKU-001 x2, SKU-002 x1`). If you only need the item count rather than a breakdown, replace the `items` field with `item_count`.
+:::
+
+## Important considerations
+
+- **Script loading order.** The main Swetrix script (added via the WordPress integration guide) must load before these event scripts run. Loading it in the `<head>` with `defer` and wrapping event code in `DOMContentLoaded` ensures the correct order.
+- **Data accuracy.** Product data (SKU, name, price) depends on how your products are configured in WooCommerce. Test each event thoroughly after setup.
+- **AJAX-heavy themes.** Some themes and page-builder plugins load pages or cart content via AJAX without full reloads. If your theme does this, the PHP-rendered `<script>` blocks may not fire for every interaction. In that case, you may need custom JavaScript event listeners tailored to your theme.
+- **Child theme or custom plugin.** All PHP snippets should go in your child theme's `functions.php` or a dedicated site-specific plugin. Editing the parent theme directly means your changes will be overwritten on the next theme update.
+- **Plugin conflicts.** If you use other analytics or tracking plugins, test for conflicts β€” multiple plugins hooking into the same WooCommerce actions can occasionally interfere with each other.
+- **Testing.** After adding each snippet, open your browser's developer console and check for JavaScript errors. Then verify that the corresponding events appear in the **Custom events** section of your Swetrix dashboard.
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 73f07fd23..1952499fc 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -15,6 +15,7 @@ module.exports = {
'integrations/framer',
'integrations/wix',
'integrations/shopify',
+ 'integrations/woocommerce',
'integrations/ghost',
'integrations/docusaurus',
'integrations/django',