Ponte Analytics for Umami

FAQ

Do I need my own Umami server, and which version?

Yes, and it must be Umami v3.x, self-hosted. Ponte Analytics for Umami connects to an Umami instance that you install and control – it does not include or host analytics itself, and it is built and tested against the v3.x tracker only. See umami.is to get started.

Is it private? Does any data go to nquare?

No data goes to nquare. The plugin is entirely client-side: the tracker script in your visitors’ browsers sends data directly to your own Umami instance. Nothing passes through, or is stored on, any server operated by nquare.

Umami itself is cookie-free by design, and you control your own instance and its data retention. This plugin adds no cookies of its own. As with any analytics tool, you remain responsible for your own privacy notice and compliance.

I don’t see any data in Umami

Work through these in order:

• Test as a logged-out visitor. Administrator, Editor and Shop Manager are excluded from tracking out of the box (Advanced tab), so your own visits usually will not appear. Use a private/incognito window.
• Check for an ad blocker or privacy extension in your browser – many block the tracker script or its requests.
• Check the Host URL. If your Umami lives in a subfolder, or you renamed the tracker script, enter the full script URL instead of just the host. Umami’s script name does not have to end in .js – for example https://example.com/analytics/app or https://example.com/stats/script.js. If Umami is at a nested base path and you have not renamed the script, end the Host URL with a trailing slash (e.g. https://example.com/analytics/) so the plugin knows it is a folder, not a script name.

How does WooCommerce purchase tracking work?

One purchase event per order, carrying revenue, currency and product info. It is fully compatible with High-Performance Order Storage (HPOS) – the plugin declares HPOS support and uses WooCommerce’s order API rather than raw post meta, so it works either way.

• When it counts. When WooCommerce considers the order paid – status Processing or Completed. Orders awaiting an offline payment (bank transfer, cheque and similar) are not counted at checkout; they are counted if and when the customer returns to the order-received page after the order has been marked paid. Marking an order Completed is a fulfilment step, not the trigger – an order already in Processing is already paid and already counted.
• Refunds are not deducted. The event was sent at the time of the sale, and this plugin is purely client-side – it cannot retract an event once sent, and Umami’s tracker offers no way to. A refunded order’s revenue stays in your Umami revenue report. Refunding does not send a second event.
• Exclude the order-received page from full-page caching. A cached copy of that page would replay the same purchase event to every later visitor who lands on it. Most caching plugins already exclude cart, checkout and account pages – check the order-received page specifically.
• Speculative loading (WP 6.8+) is a bounded, self-healing edge case. Prefetches are ignored, so they never consume the one-shot tracking flag. If the browser then serves the page from that prefetch, the visitor sees no purchase event – but the flag stays unburned, so a reload still tracks it correctly.

Which form plugins are supported?

Contact Form 7 and WPForms. A successful submission fires a custom Umami event that you name and configure from the form’s own editor – a validation error or a failed submission never fires it.

WPForms confirmations that redirect off your own site are the one exception, and it depends on the form’s AJAX setting. With AJAX on, WPForms confirms success on your own site before the browser navigates away, so the event is tracked. With AJAX off, the plugin cannot confirm success on a page it does not control, and the event is not tracked. Confirmations that stay on your own site – including the default Message confirmation and same-origin Page/Redirect confirmations – are tracked normally.

Does automatic click tracking work with page builders?

Yes – the tracker script and page-view tracking work with any theme or page builder.

Elementor is a detected integration (Events & integrations tab, on by default when Elementor is active): its buttons are tracked automatically as link events with their destination URL, even when “Link clicks” is off. If you have just switched this on, an already-cached Elementor page will not pick it up until you clear Elementor’s cache or re-save the page; switching it back off takes effect immediately.

Other builders usually render their “button” elements as links, so turn on “Link clicks” (and “Outbound links” for buttons pointing elsewhere) to record them. “Button clicks” covers native, standalone HTML buttons; a form’s submit button is covered by “Form submissions” instead.

Widgets that only change what is shown without navigating – accordions, tabs, toggles, sliders – fire no event. (Some image lightboxes are a plain link to the image file; those record as a link click when “Link clicks” is on.) To track one, send your own event with the developer API.

How do I use the JavaScript developer API?

Call window.ponteAnalytics.track( 'event_name', { key: 'value' } ) from your own JavaScript to send a custom event. A few things to know:

• It runs on the front end for visitors who are actually tracked. Excluded roles get no tracker and no API, so test while logged out or in a private/incognito window.
• Call it after the page has loaded, or on a user interaction. Events fired before the Umami tracker has loaded are not queued, so a call at the very top of the page can be missed.
• The event name is capped at 50 characters, matching Umami’s own limit – characters outside the Basic Multilingual Plane, such as most emoji, count as two. Your data object is passed to Umami as-is and is subject to Umami’s own data limits.

I was using Stats Umami 1.2.0 – how do I move to this plugin?

Deactivate and delete Stats Umami first, then activate this plugin. This matters: the plugin folder is different, so WordPress installs this one alongside the old one instead of replacing it – if both end up active at once, the tracker loads twice and every page view and event is counted twice.

After switching over:

• Your settings do not carry over. Re-enter your Umami Host URL and Website ID and turn tracking back on.
• Per-form event settings do not carry over either. Contact Form 7 and WPForms event names and data are stored per form, so open each form you had configured and set its event again.
• Analytics you already collected are unaffected – they live on your own Umami server, not in WordPress. Past WooCommerce orders that were already reported are not counted a second time.