Server-Side CAPI & Event Tracking

Bypass adblockers and ITP restrictions by routing MousePlayer traffic through your own First-Party Server-Side GTM container, and track deep E-commerce analytics.

1. Tracking Modes Overview

MousePlayer V2 introduces a powerful Event Router that allows you to control how data flows from your user's browser to our servers. You can choose from three distinct modes:

  • Web Only (Default): Streams all data via WebSockets directly to MousePlayer. Best for real-time Live View, but vulnerable to heavy adblockers.
  • Hybrid Mode: The best of both worlds. Sends lightweight mouse/scroll coordinates via WebSockets for smooth Live View, while heavy DOM mutations and Custom Events are batched and routed securely through your Server-Side GTM via HTTP POST.
  • Pure CAPI: 100% HTTP POST batching. Maximum privacy, zero WebSockets, fully first-party. Note: Live View is disabled in this mode.

2. Google Tag Manager Setup (Recommended)

The easiest way to implement Hybrid or Pure CAPI modes is by utilizing our official GTM Community Templates. Download the .tpl files below and import them into your GTM workspaces.

Download Templates:

↓ Web GTM: MousePlayer SDK Tag

↓ Server GTM: MousePlayer Ingest Client

↓ Server GTM: MousePlayer Connector Tag

Step 1: Configure the Server-Side Client & Tag

In your Server-Side GTM container, import the Ingest Client template. Set it to listen on a custom path (e.g., /mp_capi). Then, import the Connector Tag, configure it to fire on the mouseplayer_batch event, and deploy your container.

Step 2: Configure the Web GTM Tag

In your Web GTM container, import the SDK Tag. Select "Configuration & Initialization" as the Tag Type, input your Channel ID, select Hybrid Mode, and paste your ssGTM Endpoint URL (e.g., https://metrics.yourdomain.com/mp_capi).

3. Manual Installation (Without GTM)

If you prefer hardcoding the script, you must define the window.mp_config object before loading the tracking snippet.

<!-- MousePlayer Config & SDK --> <script> window.mp_config = { channel: 'YOUR_UNIQUE_ID_HERE', mode: 'hybrid', // 'web_only', 'hybrid', or 'pure_capi' capi_endpoint: 'https://metrics.yourdomain.com/mp_capi' }; window.mp = window.mp || function() { (window.mp.q = window.mp.q || []).push(arguments); }; (function(w, d, s) { var f = d.getElementsByTagName(s)[0], j = d.createElement(s); j.async = true; j.src = 'https://www.mouseplayer.com/mp.js'; f.parentNode.insertBefore(j, f); })(window, document, 'script'); </script>

4. E-Commerce Funnel Tracking

Track the complete customer journey. Using standardized event names allows MousePlayer to automatically generate beautiful E-Commerce Funnel reports in your project workspace. All events are fully compatible with CAPI and Web-Only modes.

1. view_item

Trigger this event when a user views a specific product page.

mp('event', 'view_item', { item_id: 'SKU_98765', item_name: 'Wireless Noise-Cancelling Headphones', item_category: 'Electronics', price: 299.99 });

2. add_to_cart

Trigger this event when a user adds an item to their shopping cart.

mp('event', 'add_to_cart', { item_id: 'SKU_98765', item_name: 'Wireless Noise-Cancelling Headphones', price: 299.99, quantity: 1 });

3. begin_checkout

Trigger this event when a user proceeds to the checkout screen.

mp('event', 'begin_checkout', { cart_value: 299.99, currency: 'USD', total_items: 1 });

4. purchase

Trigger this event upon successful payment or order confirmation.

mp('event', 'purchase', { transaction_id: 'T_1002938', value: 299.99, tax: 24.00, shipping: 0.00, currency: 'USD', coupon_used: 'FREESHIP' });

5. Custom Events & Lead Generation

You are not limited to e-commerce. Track form submissions, newsletter signups, or custom interactions unique to your web application.

Lead Generation (Form Submit)

Fire this event when a user successfully submits a contact form or requests a quote.

mp('event', 'generate_lead', { form_name: 'B2B Contact Form', industry: 'Software Development', company_size: '50-200' });

Custom UI Interaction

Understand how users interact with complex elements like calculators, modals, or tab switches.

mp('event', 'calculator_used', { loan_amount: 50000, duration_months: 48, interest_rate: 7.5 });

6. Parameter Limits & Guidelines

Data Typing: MousePlayer automatically detects parameter types. Send numbers as integers or floats (e.g., 150.00, not "150.00") to enable advanced numerical filtering (e.g., "Price > 100") in the dashboard.

Rule Description
Event Name Length Maximum 128 characters. Use snake_case for best readability (e.g., user_signup).
Parameter Key Length Maximum 64 characters per key name (e.g., transaction_id).
String Values Text parameters are truncated to 255 characters to ensure optimal database performance.
Data Privacy Do not send Personally Identifiable Information (PII) such as raw email addresses, real names, or passwords as event parameters.