OSSEngine Analytics Connector

By mostafamatar

0+ active installationsVersion 1.1.0

Connect WordPress to privacy-friendly, cookie-free analytics in one click. No pasted scripts, IDs, or credentials.

Description

OSSEngine Analytics Connector is an independent WordPress plugin built by OSSEngine. It connects your website to the UmamiEngine managed analytics service (umamiengine.com), or to your own self-hosted Umami analytics instance.

UmamiEngine is managed hosting for the open source Umami Analytics software, published under the MIT license. This plugin is an independent third-party connector. It is not affiliated with, endorsed by, sponsored by, or supported by the Umami project, and it is not an official Umami plugin. The name “Umami” is used only to describe the open source software this connector works with.

What data is transmitted?

Pageviews send the page URL, referrer, browser language, screen size, and device type to your analytics instance — the same data the standard Umami Analytics tracker collects. WooCommerce events additionally send product IDs/SKUs, product names, prices, item counts, and order values with currency. Every WooCommerce event carries a salted, one-way event_id (an HMAC derived from the event name, order ID, and order key) so retries and reloads can be deduplicated without exposing your WordPress order IDs. The raw WooCommerce order ID is not sent unless an administrator explicitly enables “Send the raw WooCommerce order ID” in the Advanced tab. The plugin never sends customer email, name, address, phone, or payment information.

Consent is evaluated in the visitor’s browser at event time, so cached HTML contains no per-visitor state. If the optional server-side fallback is enabled (off by default), purchases are sent from your WordPress server to the configured Umami host after the browser did not confirm delivery; that request uses a browser-like User-Agent and never forwards the visitor’s IP address.

External services

This plugin talks to the following external services. It does not contact any other external servers on its own.

UmamiEngine integration API

This plugin connects to the UmamiEngine integration API at https://api.umamiengine.com (the plugin’s default API URL) to link your WordPress site to UmamiEngine and to configure or manage the analytics integration and its associated functionality.

UmamiEngine service: https://umamiengine.com
Terms of Use: https://umamiengine.com/terms
Privacy Policy: https://umamiengine.com/privacy

These are server-to-server requests made by your WordPress install, not by your visitors’ browsers. They are only made while an administrator is setting up or managing the integration.

What data is transmitted:

  • Your WordPress site URL (the value of home_url()), so the correct site can be connected and registered.
  • A name for your analytics website — your WordPress site title, or the site hostname if no title is set.
  • A one-time authorization code and a one-time security (CSRF) state value, used to complete the connection you approved on the UmamiEngine dashboard.
  • The site token that UmamiEngine issued for this integration, sent in the Authorization header as a Bearer credential. This is a token created specifically for the plugin integration; your WordPress login credentials, email, or other account data are never sent.
  • The plugin’s own version string, sent in an X-Plugin-Version header with every request.
  • The word “DELETE” as a confirmation value, sent only when you confirm disconnection.

When it is transmitted:

  • When an administrator completes the “Connect UmamiEngine” flow: after you approve the connection on the UmamiEngine dashboard, the plugin exchanges the authorization code for the integration details, registers your Umami website, and downloads the tracking configuration. If the website registration did not complete earlier, it is retried on a later status refresh.
  • When an administrator clicks “Refresh status” on the settings page.
  • Once per week through a scheduled WordPress event, as long as a managed connection is active, to revalidate the connection and refresh the cached tracking configuration. It does not run on page views.
  • When an administrator opens the plugin settings page while a managed connection is active, a single status request is made to detect a disconnection done from the UmamiEngine dashboard side. Transient server failures do not change anything on your site.
  • When an administrator confirms disconnection by typing DELETE, which permanently deletes the Umami website and its analytics data at the service.

No page content, post data, email addresses, visitor data, or other site content is transmitted through this API.

UmamiEngine dashboard (connect page)

When an administrator clicks “Connect UmamiEngine” (or “Reconnect”), the browser is redirected to the UmamiEngine dashboard at https://dashboard.umamiengine.com where the connection is approved. The redirect URL contains your site URL and a one-time random security (state) value that ties the round trip to your site. No files, credentials, or content are sent; the plugin returns to WordPress afterwards. This happens only when an administrator starts the connect flow.

Umami analytics tracking script

When the plugin is connected and tracking is enabled, a tiny inline bootstrap on your site’s public pages loads the Umami analytics tracking script from your configured analytics host — the Umami instance hosted for you by UmamiEngine, or your own self-hosted Umami instance in “Existing Umami” mode. The bootstrap prints only public configuration (script URL, website ID, consent mode/category, exclusion flag) and is identical for every visitor, so it is safe with full-page caches. It injects the tracker only after consent and role-exclusion checks pass. The ossengine_tracking_enabled filter remains a hard override.

Pageviews send the page URL, referrer, browser language, screen size, and device type. If WooCommerce is installed, WooCommerce event tracking is enabled in the plugin settings, and tracking is active, e-commerce events add product ID/SKU, product name, price, item count, and order value with currency, plus a salted one-way event_id used for deduplication. Raw order IDs are only included when the administrator enables that opt-in; by default they are not sent. The script does not send customer email, name, address, phone, or payment information. Administrators and shop managers are excluded by default, and tracking is off until you connect, so activation alone makes no external requests.

When the optional server-side fallback is enabled (off by default), the WordPress server may POST a confirmed purchase/refund event to the same Umami host using its /api/send endpoint. Such requests happen only in deferred cron/Action Scheduler contexts, never during checkout or page rendering, carry no client IP address, and are sent only when the order’s stored consent snapshot granted tracking.

Terms of Use: https://umamiengine.com/terms
Privacy Policy: https://umamiengine.com/privacy

Your own Umami instance (Existing-Umami mode)

If you choose “Existing Umami” mode, the plugin connects only to the Umami base URL you enter, which points at your own installation — not to UmamiEngine. When an administrator saves the settings with Existing-Umami mode enabled, the plugin validates the instance with two GET requests to that URL (the Umami website endpoint for the Website ID you entered, and the /script.js tracker file) to confirm the instance and ID are usable. These requests carry no data in the body; the Website ID is part of the request URL. They are made only during this validation, never during normal page loads. After validation, tracking data is sent by visitors’ browsers to your own instance as described in the tracking section above.

Installation

  1. Install the plugin and activate it.
  2. Go to Settings → OSSEngine Analytics. New to OSSEngine? Click “New to OSSEngine? Sign up now” to create your account (14 days free, no credit card).
  3. Click “Connect OSSEngine Analytics” and approve access — done. Tracking starts automatically.
  4. Click “Open analytics” to view your stats directly in the analytics app (app.umamiengine.com).

For an existing self-hosted Umami instance, choose “Existing Umami” and enter your Umami URL and website ID instead.

FAQ

Will analytics slow down my site?

No. The tracking script loads asynchronously and the plugin never makes blocking API requests while rendering pages. If analytics is unreachable, your site is unaffected.

Is this an official Umami plugin?

No. OSSEngine Analytics Connector is an independent product built by OSSEngine. It is not affiliated with, endorsed by, sponsored by, or supported by the team behind Umami.

What happens when I disconnect or uninstall?

Disconnecting revokes plugin access and stops tracking. All data on UmamiEngine will be deleted. Uninstalling removes the plugin’s settings, queue table, and scheduled tasks. Order meta (the consent snapshot and purchase dedupe state) is kept by default so deactivating and reactivating loses nothing; an administrator can opt in to deleting it under Settings → OSSEngine Analytics → Advanced → Data removal before uninstalling.

How does the connector handle consent withdrawal and a reloading checkout thank-you page?

Consent is checked in the browser every time an event is about to be sent. When a visitor withdraws consent (through your consent plugin, or by calling window.ossengineConsent.revoke()), the tracker is disabled, pending client events and all of the plugin’s sessionStorage dedupe keys are purged, the Umami script tag is removed, and the withdrawal is broadcast to other open tabs. Server-side queued events that carry that visitor’s consent token are purged immediately.

The WooCommerce thank-you page is safe to reload, revisit with the browser Back button, or open in several tabs: a purchase moves through claimed → delivered in order meta. The beacon is rendered while the order is claimed (up to a bounded number of attempts), and the browser confirms delivery to a nonce-free REST endpoint authenticated by the order key plus the salted event_id (checked with hash_equals and rate-limited). delivered is terminal, so later loads print nothing. The browser beacon is the authoritative purchase source; the optional server-side fallback only runs when the browser never confirms and the stored consent snapshot granted tracking.

Why is the tracking script not printed like other analytics plugins?

Version 1.1.0 replaces the per-request <script> tag with a tiny dependency-free inline bootstrap (under 1.5 KB) that is identical for every visitor. It contains only public configuration (script URL, website ID, consent mode/category, exclusion flag) and injects the Umami tracker only after the consent/exclusion checks pass. This keeps the HTML cache-safe and lets the same markup work for logged-in, logged-out, and consenting visitors. The ossengine_script_position filter still chooses head or footer placement, and ossengine_tracking_enabled remains a hard override that suppresses all output.

Does the connector work with my consent plugin?

Yes. In “Auto” mode it detects the WP Consent API and follows the statistics category (change it in the Advanced tab). It also listens for wp_listen_for_consent_change and exposes window.ossengineConsent.grant(), revoke(), and isGranted() for custom integrations. Most consent plugins can call the interface with a one-liner after their own state changes:

  • Complianz: document.addEventListener('cmplz_status_change', function (e) { if (e.detail && e.detail.category === 'statistics' && e.detail.value === 'allow') window.ossengineConsent.grant(); else if (e.detail && e.detail.category === 'statistics') window.ossengineConsent.revoke(); });
  • CookieYes: document.addEventListener('cookieyes_consent_update', function (e) { window.ossengineConsent[e.detail.accepted.includes('analytics') ? 'grant' : 'revoke'](); });
  • Cookiebot: window.addEventListener('CookiebotOnAccept', function () { window.ossengineConsent[Cookiebot.consent.statistics ? 'grant' : 'revoke'](); });
  • Real Cookie Banner: call window.ossengineConsent[window.rcb && rcb.isConsentGiven ? 'grant' : 'revoke']() from its consent-changed callback.
  • Borlabs Cookie: document.addEventListener('borlabsCookieAfterConsent', function () { window.ossengineConsent[borlabsCookie.Groups.statistics ? 'grant' : 'revoke'](); });

If your consent plugin is not detected in “Auto” mode, switch to “Require consent” so nothing loads until you call grant().

Screenshots

Changelog

1.1.0

  • New: exactly-once WooCommerce purchase tracking with a claimed → delivered state machine, nonce-free order-key + HMAC confirmation endpoint, and a stable salted event_id.
  • New: consent modes (Auto / Require consent / Always track), WP Consent API integration, window.ossengineConsent JS interface, cross-tab withdrawal propagation, cache-safe role exclusion, and per-order consent snapshots.
  • New: dependency-free JavaScript rewrite (under 3 KB) covering classic and block cart/checkout, Store API add/remove, AJAX fragments, and non-AJAX add-to-cart forms.
  • New: bounded server-side event queue with a versioned table, eviction limits, exponential backoff, dead-lettering, Retry-After handling, a circuit breaker, and an optional off-by-default server-side fallback.
  • New: Advanced settings tab (consent, trigger status, order-ID opt-in, excluded roles, queue limits, fallback toggle), queue status panel, read-only order metabox, and privacy exporter/eraser/policy text.
  • Improved: tracking is now loaded by an inline cache-safe bootstrap instead of a per-request script tag; ossengine_script_position and ossengine_tracking_enabled keep working.
  • Improved: strict per-event payload allowlist with PII scrubbing, 8 KB cap, and extend-only schema filters.
  • Improved: cleanup on uninstall now covers all v1.1.0 options, the queue table, and scheduled hooks; order meta is removed only on explicit opt-in.
  • Fixed: begin_checkout dedupe now uses the cart hash instead of the session id; legacy 1.0.0 delivery markers migrate without re-firing purchases.

1.0.0

  • Initial release: one-click UmamiEngine connect, automatic tracking, admin exclusion, Existing-Umami mode, WooCommerce status.