Debouncing High-Frequency WebGL 3D CAD Viewport & Calculator Events in Matomo Tag Manager

When instrumenting browser-based 3D CAD mesh viewers (Three.js / WebGL2) and interactive engineering calculators with Matomo Tag Manager (_mtm / _paq), binding trackEvent directly to canvas orbit controls, slider inputs, or real-time tolerance recalculations can easily fire 30–60 tracking requests per second.

Besides saturating the visitor’s network queue and causing main-thread frame drops during 3D orbit rotation, unthrottled viewport events quickly pollute Matomo’s log_link_visit_action table.

Here is the lightweight Custom HTML / JavaScript pattern we use in Matomo to capture meaningful engineering interaction telemetry without degrading 60 FPS WebGL rendering:


1. Decouple Real-Time UI State from _paq.push Using requestIdleCallback

Instead of firing _paq.push(['trackEvent', ...]) inside the input or pointermove listener, debounce the final settled parameter state by 800 ms and schedule the Matomo payload inside requestIdleCallback:

const createMatomoEngineeringTracker = (delayMs = 800) => {
  let timerId = null;

  return function trackSettledAction(category, action, name, numericValue) {
    if (timerId) clearTimeout(timerId);
    timerId = setTimeout(() => {
      const dispatch = () => {
        window._paq = window._paq || [];
        window._paq.push([
          'trackEvent',
          category,
          action,
          name,
          typeof numericValue === 'number' ? Math.round(numericValue * 100) / 100 : undefined
        ]);
      };
      if ('requestIdleCallback' in window) {
        window.requestIdleCallback(dispatch, { timeout: 2000 });
      } else {
        dispatch();
      }
    }, delayMs);
  };
};

// Usage on a 3D mesh parser or engineering calculator:
const trackCalc = createMatomoEngineeringTracker(800);

2. Bucket Continuous Engineering Metrics into Semantic Event Names

If users are inspecting 3D STL/STEP file geometry (such as triangle counts, non-manifold edge counts, or bounding-box volume), pushing raw high-cardinality floats into the Event Name dimension fragments Matomo’s aggregated reports.

  • Event Category: 3D_Mesh_Inspector
  • Event Action: Analyze_Topology
  • Event Name (Bucketed): 100k_to_500k_Triangles (keeps cardinality low in Matomo reports)
  • Event Value (Numeric): Pass the exact parse duration in milliseconds (e.g., 142) so Matomo automatically computes Avg. Event Value across hardware tiers.

We run this exact debounced telemetry pattern in production on our client-side 3D STL & CAD Mesh Topology Checker to benchmark WebGL parsing performance without impacting viewport responsiveness.

3. Combine with sendBeacon for Unload Reliability

Ensure _paq.push(['alwaysUseSendBeacon']); is enabled before trackPageView so queued idle events still flush cleanly if an engineer closes the tab immediately after exporting their calculation results.