Event Tracking for WordPress

AutoROICalc Event Tracking turns selected WordPress interactions into AutoROICalc records. It supports Gutenberg, Elementor, forms, user registrations, custom CSS targets, marketing attribution, structured breakdowns, and authenticated reports in the WordPress administration Dashboard.

Use this plugin when the business meaning of an interaction matters more than a generic page view—for example, a pricing-button click, contact-link hover, brochure download, validated form submission, or completed registration.

Install and Connect

1. In WordPress, open Plugins → Add New Plugin.
2. Search for AutoROICalc Event Tracking, install it, and activate it.
3. Follow the guided setup under Settings → Events Tracking.
4. Sign in to an existing AutoROICalc account, create an account, or enter a service token manually.
5. Enable event tracking and save the settings.
6. Use Diagnostics → Send test event to confirm server delivery.

The guided connection creates a separate, restricted service token for the WordPress installation. The temporary login session is closed after the token is created, and WordPress does not store the entered account password.

For managed installations, see WordPress plugin configuration.

Track a Gutenberg Button

1. Edit the page or post and select a Button block.
2. Open Event Tracking in the block sidebar.
3. Enable tracking for the button.
4. Select one or more interactions: Button click, Mouse hover, and Visible in viewport.
5. Configure the record type and description for every selected interaction.
6. Review value, activity, debounce or dwell timing, sources, tags, consent, and optional breakdown data.
7. Update the page and test the interaction as a visitor.

One target can report several interactions independently. For example, the same call-to-action can create pricing_cta_visible, pricing_cta_hover, and pricing_cta_click records. Each interaction has its own signed configuration, event key, and debounce state.

Supported Gutenberg content

• Button blocks
• Navigation Link blocks
• Linked Image blocks
• Links inside Paragraph blocks
• Links inside Heading blocks
• Links inside List Item blocks

For a text block containing several links, one editor configuration applies to the block. Each rendered link still receives its own target position and event identity.

Configure Interactions

Setting	Purpose
Record type	Stable identifier used for filtering and reporting
Description	Human-readable meaning of the interaction
Activity	Optional activity classification
Value	Optional numeric business value assigned to the event
Debounce	Prevents repeated activity on the same target from inflating counts
Dwell time	Requires hover or visibility to last before creating a record
Sources	Uses captured attribution or a fixed source override
Tags	Groups events across pages, campaigns, or funnels
Consent category	Applies the configured analytics, marketing, or site-managed gate
Breakdowns	Adds validated structured dimensions and metrics to custom_data

The default debounce window is 10 seconds. The first event is sent immediately; matching activity on the same target is ignored until the window expires. Disable or override it only when every repeated interaction is meaningful.

Elementor Support

The following Elementor widgets expose an Event Tracking section in their Content controls:

• Button
• Icon List
• Text Editor
• Image
• Heading
• Icon
• Icon Box
• Image Box
• Call to Action with Elementor Pro

The same click, hover, viewport visibility, value, tags, source, consent, debounce, dwell, and breakdown options are available. Multi-link widgets identify each rendered link separately using its visible label, destination, and stable position.

Elementor Pro Forms

Add AutoROICalc Event under Actions After Submit, then configure the AutoROICalc Event section. A record is sent only after Elementor Pro processes a browser-validated submission.

Form values are excluded by default. You may explicitly allowlist up to 20 non-sensitive Elementor field IDs for raw_data.form.fields. Password, file-upload, CAPTCHA, and honeypot fields are always excluded.

Minimize submitted data

Do not allowlist personal or sensitive fields unless you have a documented purpose, appropriate disclosure and consent, access controls, and a suitable retention policy.

Other Supported Events

Forms

Optional automatic form tracking supports:

• Browser-validated native forms
• Contact Form 7 success events
• Gravity Forms confirmations

Field names and submitted values are not collected by automatic form tracking.

WordPress registrations

The plugin can create a count record when WordPress creates a user, including a WooCommerce customer registration. Configure the record type, description, tags, and captured or fixed sources under Settings → Events Tracking.

Registration records do not contain the email address, username, display name, password, or WordPress user ID. They may contain the assigned role, front-end or administration context, page path, and consent-aware attribution.

Custom page elements

Use a custom CSS selector profile when a theme or plugin renders an element without native Gutenberg or Elementor controls. Each profile can track any combination of click, hover, and viewport visibility, with independent record settings for each interaction.

Keep selectors narrow and stable. Test them after changing the theme or page-builder layout.

Source / Medium Attribution

Choose between:

• Captured marketing sources — use UTM parameters and referrer information collected by the plugin runtime.
• Fixed source override — always use the administrator-defined source values for that target.

Captured values use familiar source / medium labels such as:

• (direct) / (none)
• google / organic
• google / cpc
• example.com / referral

This attribution is independent from Google Analytics. The plugin neither loads Google Analytics nor reads a Google Analytics account.

Language Attribution

Open Settings → Events Tracking → Event tracking → Event behavior and attribution and enable Page language to include the displayed language in record breakdowns.

When enabled, the plugin:

• Uses the current WPML language when WPML is available
• Falls back to the WordPress locale otherwise
• Adds a website_language breakdown
• Adds the language code, locale, and provider to record context and raw page data

This is useful when the same button, form, or registration funnel appears in several languages.

Structured Breakdown Data

Tracked targets can attach validated breakdown JSON. A simple button context can look like this:

[
  {
    "key": "button_context",
    "title": "Button context",
    "items": [
      {
        "key": "pricing_demo",
        "title": "Request a demo",
        "metrics": [
          {
            "key": "clicks",
            "unit": "count",
            "title": "Button clicks",
            "value": 1
          }
        ],
        "attributes": {
          "placement": "pricing",
          "variant": "primary"
        }
      }
    ]
  }
]

Keep keys stable across pages and releases so Breakdown widgets can group the records consistently. See the Records API for the record model.

WordPress Dashboard Report Widgets

The plugin can add private AutoROICalc reports to wp-admin/index.php:

1. Enable authenticated widget access on the report in AutoROICalc.
2. Open Settings → Events Tracking → Dashboard widgets.
3. Add a widget and select the report by ID and name.
4. Select a configured Data Value, Gauge, or Target widget, or create a line, bar, pie, or doughnut chart from selected report datasets.
5. Choose the height, save the settings, and open the WordPress Dashboard.

WordPress requests the widget server-to-server with the service token and presents it through a protected iframe to authorized administrators. The report does not need public access. Learn more in the Report Widget API guide.

Privacy, Consent, and Browser Storage

Anonymous event counting

In a tracked Gutenberg block or Elementor link/button widget, choose Tracking mode → Anonymous event counting. Custom CSS selector targets support "tracking_mode": "anonymous":

[
  {
    "selector": ".pricing-signup",
    "tracking_mode": "anonymous",
    "events": {
      "click": { "type": "button_click", "description": "pricing_signup" },
      "hover": { "type": "button_hover", "description": "pricing_hover", "dwell_ms": 750 },
      "visible": { "type": "button_visible", "description": "pricing_visible", "dwell_ms": 1000 }
    }
  }
]

Use static record types and counter names without personal data. The same type and name identify the same counter across pages; use separate labels to report clicks, hover and visibility separately. Each event creates a record with value 1, source anonymous events, tag anonymous-event, and the API's current UTC date with time 00:00:00. Sum values to report event totals. These are interaction totals, not unique visitors; repeated interactions count again. Hover and visibility retain their configured dwell thresholds, using only in-memory timers. Configured values, debounce, tags, breakdowns, language context and attribution are ignored in this mode.

Anonymous requests contain only a signed counter definition. They omit credentials and referrers, use no cookies or browser storage, and contain no user/visitor/session identifiers, per-click IDs, browser timestamps, DOM labels, paths or campaign sources. The separate /wp-json/autoroicalc/v1/anonymous-events endpoint rejects extra payload fields and does not forward browser metadata or run attribution record filters. It applies a shared per-counter limit of 600 requests per minute, adjustable through autoroicalc_anonymous_event_rate_limit; rejected or failed requests are not retried automatically.

Deploy the API's /service_token/anonymous-event endpoint before enabling this mode. The API separately limits anonymous requests to 600/minute per publisher database per worker and applies normal record plan limits. It constructs the anonymous record itself and permits repeated identical clicks without ordinary record deduplication.

The web server still receives normal network information such as IP addresses and user-agent headers, and records retain the database's normal insertion timestamp. Configure infrastructure/access logs and retention accordingly. This technical mode is not a blanket legal exemption from consent requirements.

Keep Require explicit browser consent signal selected for attribution tracking and use Analytics or Marketing as its consent category. Anonymous counters can operate before that consent; granting consent does not add attribution to their records. Other enabled integrations and the consent manager may independently use their own storage.

Attribution tracking

For a plain-language overview of tracking modes, consent signals, and site responsibilities, see Tracking and Consent.

The Consent category choices are Analytics, Marketing and No runtime consent gate, consistently in Gutenberg and Elementor. No runtime consent gate skips the event's consent check; it does not make tracking anonymous. Normal browser storage, attribution and event details may still be used. The global Consent mode → Consent is managed by the site also bypasses internal consent checks without changing the data collected.

For anonymous counts, select Tracking mode → Anonymous event counting instead. That mode restricts the payload and avoids browser storage and attribution, independently of the consent-category setting.

The plugin does not use long-lived attribution cookies.

Storage	Purpose
Local storage	Retains recent captured source / medium attribution
Session storage	Retains optional debounce state for the current browser tab
arc_consent session cookie	Passes granted consent categories to supported server-side integrations
arc_sources session cookie	Passes up to six sanitized attribution labels to server-side form and registration tracking

The session cookies use SameSite=Lax, use Secure on HTTPS sites, and do not contain form entries, account identity details, the service token, or a unique visitor identifier.

The default consent mode waits for an explicit signal for Analytics or Marketing events:

window.AutoRoiCalc.setConsent({
  analytics: true,
  marketing: false
});

A consent manager can instead dispatch an autoroicalc:consent browser event with the same values. Select Consent is managed by the site only when the site establishes an appropriate consent or other lawful basis before tracking runs.

Activity from logged-in administrators is excluded by default. This prevents editing and routine testing from distorting reports; temporarily disable the exclusion only for deliberate tests.

Diagnostics and Troubleshooting

Start with Settings → Events Tracking → Diagnostics:

1. Confirm that the connection is ready and tracking is enabled.
2. Send a server-side test event.
3. Enable debug mode temporarily.
4. Test the page as a logged-out visitor or allow administrator activity temporarily.
5. Check the detected, sent, and skipped event counts, current consent state, and latest REST status.

If an event is not sent, verify:

• The target has tracking enabled and the page was updated
• Every selected interaction has a record type and description
• The service token is valid
• The interaction's consent category is granted
• The debounce or dwell configuration is not suppressing the test
• A cache or optimization plugin is not serving old page markup or JavaScript
• Custom selectors still match the rendered page

Uninstall Behavior

Plugin settings and local connection data are retained by default. Enable uninstall cleanup under Data retention before uninstalling if those settings should be removed.

Cleanup does not delete records already sent to AutoROICalc, remove tracking attributes stored in Gutenberg or Elementor content, or revoke the installation token. Revoke unused tokens from Integrations in AutoROICalc.

Related Docs

WordPress Plugins Generic Web Event Tracking Report Widget API