=== AutoROICalc Event Tracking ===
Contributors: autoroicalc
Tags: click tracking, event tracking, conversion tracking, forms, analytics
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Track WordPress clicks, forms, user registrations, engagement, and source/medium attribution with AutoROICalc.

== Description ==

AutoROICalc Event Tracking helps you measure the WordPress interactions that matter: link clicks, button clicks, form submissions, new user registrations, engagement, and custom page elements.

Add click tracking directly from the WordPress block editor, without adding JavaScript snippets to individual pages. Choose what each interaction means, how it should be valued, which tags and attribution sources it should use, and whether repeated activity should count as one event.

The browser sends events to your own WordPress site first. WordPress validates the signed event configuration and relays the record to AutoROICalc with a server-side service token. Your service token is never exposed to visitors.

Activity from logged-in site administrators is excluded by default so content editing and testing do not distort reporting. This exclusion can be disabled temporarily under Event tracking when administrator activity should be measured deliberately.

An AutoROICalc account and service token are required to send records. The guided connection can create a restricted service token for the current WordPress installation without storing your AutoROICalc password or regular app session tokens.

= Guided setup and per-site connection =

After activation, the plugin opens a guided setup on Settings -> Events Tracking. Existing AutoROICalc users can sign in once to create a separate, restricted service token for that WordPress installation. The temporary account session is closed immediately after the token is created.

New users can create an AutoROICalc account from the same screen after explicitly accepting the AutoROICalc Terms of Service and reviewing the Privacy Policy. Email verification is required before connecting the site. Manual service-token entry and the `AUTOROICALC_SERVICE_TOKEN` constant remain available.

The setup guide also points administrators to their first tracked Button or link, the delivery test, and optional WordPress Dashboard reporting.

= WordPress click tracking =

Track clicks on:

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

For text blocks containing multiple links, one editor configuration applies to the block while every rendered link receives its own event identity and target position. Link records can distinguish internal links, outbound links, and other URL schemes.

= Event tracking from the block editor =

The Event Tracking panel lets editors configure:

* Click, mouse hover, or viewport visibility triggers
* AutoROICalc record type and description
* Activity, numeric value, and tags
* Captured campaign sources or fixed source overrides
* Consent category
* Debounce behavior for repeated interactions
* Optional AutoROICalc breakdown data

Hover and visibility tracking support a configurable dwell time so brief or accidental interactions do not have to become records.

= Form and custom event tracking =

Optional form tracking supports validated native WordPress forms, Contact Form 7 success events, and Gravity Forms confirmations. Form field names and submitted values are never collected.

Custom targets let administrators track page elements that are not supported blocks. Add up to 20 CSS selector profiles and choose click, hover, or visible-in-viewport triggers.

= WordPress user registration tracking =

Optionally create an AutoROICalc count record whenever WordPress creates a user account, including WooCommerce customer registrations. Administrators can configure the registration record type, description, tags, and whether its attribution uses captured sources or a fixed source list.

Registration records do not contain the account email address, username, display name, password, or WordPress user ID. They may include only non-identifying context such as the assigned role, whether the account was created through the front end or WordPress administration, the registration page path, and consent-aware source / medium attribution.

= Elementor event tracking =

Elementor Button, Icon List, Text Editor, Image, Heading, Icon, Icon Box, Image Box, and Call to Action widgets include an Event Tracking section with the same click, hover, visibility, value, tag, attribution, consent, debounce, and breakdown options used by WordPress blocks. Multi-link widgets track every rendered link separately using its visible text, destination, and stable position in the widget. Call to Action requires Elementor Pro.

Elementor Pro Forms can add AutoROICalc Event under Actions After Submit. A record is created only for a browser-validated submission processed by Elementor Pro. The action can use captured source / medium attribution or fixed sources.

Form values are excluded by default. Administrators may explicitly allowlist up to 20 Elementor field IDs for inclusion under `raw_data.form.fields`. Only those selected values are read and sent. Password, file-upload, CAPTCHA, and honeypot fields are always excluded. Avoid selecting personal or sensitive fields unless you have an appropriate purpose, disclosure, consent, and retention policy.

= WordPress dashboard report widgets =

Add authenticated AutoROICalc reports to the WordPress administration Dashboard. Choose reports and datasets by name, build line, bar, pie, or doughnut charts, or display configured AutoROICalc Data Value, Gauge, and Target widgets. Compact Data Value widgets can use a reduced height, and collapsible settings cards keep multiple Dashboard widgets manageable.

WordPress retrieves each widget server-to-server with the configured service token, then displays it only to authorized administrators through a protected iframe. Reports can remain private when authenticated backend access is enabled in AutoROICalc.

= Marketing attribution and repeated clicks =

Events can use marketing sources captured by the bundled AutoROICalc runtime or a fixed source list configured by the editor. Captured attribution follows the familiar source / medium convention used by Google Analytics and other web analytics tools.

The plugin derives attribution from UTM parameters and the referring URL. Examples include `(direct) / (none)`, `google / organic`, `google / cpc`, and `example.com / referral`. Campaign values may also be captured, and recent unique sources can be attached to an event record.

This is independent AutoROICalc attribution. The plugin does not connect to Google Analytics or read data from a Google Analytics account.

Debouncing is enabled by default with a 10-second window. The first matching event is sent immediately and repeated activity on the same target is ignored until the window expires. Administrators can change the default, and editors can override or disable it for individual tracked blocks.

== Installation ==

1. Upload the plugin ZIP through Plugins -> Add New Plugin, or upload the `autoroicalc-event-tracking` folder to `/wp-content/plugins/`.
2. Activate AutoROICalc Event Tracking.
3. Follow the guided setup, or open Settings -> Events Tracking later.
4. Connect an existing AutoROICalc account to create a token for this installation, register a new account, or enter a service token manually. Review the defaults and consent mode, then enable tracking.
5. Edit a supported block and open Event Tracking in the block sidebar.
6. Enable tracking, configure the event, and update the page.

For a supported linked Elementor widget, open its Content controls and use Event Tracking. For an Elementor Pro Form, add AutoROICalc Event to Actions After Submit and configure the new AutoROICalc Event section.

The service token can instead be set in `wp-config.php`:

    define( 'AUTOROICALC_SERVICE_TOKEN', 'your-service-token' );

When this constant is set, the token field is disabled in WordPress settings and the token remains outside the WordPress database.

== Screenshots ==

1. View tracked click performance directly in WordPress with an authenticated AutoROICalc Dashboard report chart.
2. Configure global event defaults, click debouncing, marketing attribution, consent, and delivery settings.
3. Connect an existing AutoROICalc account or create an account from the guided setup screen.
4. Configure authenticated AutoROICalc report widgets for the WordPress Dashboard.
5. Enable button click tracking in the block editor and configure the record type, description, activity, and value.
6. Add debounce behavior, captured marketing sources, tags, and structured breakdown data to a tracked Button block.

== Getting started ==

= Track a WordPress button click =

Select a Button block, open Event Tracking, and enable Track this button. Choose the trigger, give the record a stable description such as `pricing_signup`, then review its value, tags, attribution, debounce window, and consent category before saving.

= Track links in WordPress text =

Select a Paragraph, Heading, or List Item containing one or more links, then enable Track links in this block. The configuration applies to every link in that block, but each link is identified separately in the generated event data.

The default link record type is `web_link_click`, the default description is `link_click`, and the default tags are `wordpress` and `link`. Editors can override these values.

== Consent and data storage ==

The plugin does not use long-lived attribution cookies. Captured source history is retained in local storage. When debouncing is enabled, the per-target expiry is retained in session storage for the current browser tab, with an in-memory fallback when browser storage is unavailable.

Server-side Elementor Pro Form and WordPress user-registration tracking may use these first-party session cookies:

* `arc_consent` contains only granted category names such as `analytics` or `marketing`. It lets server-side integrations honor the consent decision made in the browser.
* `arc_sources` contains up to six sanitized source / medium or campaign labels, such as `google / organic`. It passes captured attribution from browser storage to server-side form and user-registration tracking.

Both cookies use `SameSite=Lax`, add `Secure` on HTTPS sites, and have no explicit expiration, so they are browser-session cookies. They do not contain submitted form values, customer details, the AutoROICalc service token, or a unique visitor identifier. Whether these cookies are categorized as necessary, analytics, or marketing depends on the site's configuration and purpose.

Example wording that site owners can adapt for their cookie or privacy policy:

    AutoROICalc Event Tracking may use first-party session cookies to pass consent choices and source / medium attribution to server-side form and user-registration tracking. The cookies expire with the browser session and do not contain form entries, account identity details, or unique visitor identifiers.

The default consent mode requires an explicit browser signal before events assigned to the Analytics or Marketing consent categories are sent. A consent manager can grant consent through:

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

It can also dispatch an `autoroicalc:consent` browser event with the same values.

Choose No runtime gate for an individual event, or Consent is managed by the site globally, only when the site has established an appropriate consent or other lawful basis before tracking runs. Site administrators remain responsible for configuring tracking and consent for their jurisdiction and use case.

== Data sent to AutoROICalc ==

Depending on the event configuration, a record may include its type, description, activity, value, tags, attribution sources, page and target paths, post and block context, visible target label, link classification, trigger metadata, optional breakdowns, and a random event identifier.

When an administrator uses the guided connection, WordPress sends the entered AutoROICalc login and password directly to the AutoROICalc API over HTTPS. It uses the returned temporary session only to create a service token restricted to record writing and report-widget access, then immediately logs out. The password, access token, and refresh token are not stored by WordPress. When creating a new account, the submitted email, optional username, password, language, Terms acceptance, and WordPress application type are sent to AutoROICalc for registration and email verification.

Form contents and customer details are excluded by default. If an administrator explicitly allowlists Elementor Pro Form field IDs, the corresponding submitted values are sent server-to-server under `raw_data.form.fields`. WordPress registration records never include the account email address, username, display name, password, or WordPress user ID; they may include only the assigned role, registration context, page path, and configured attribution. The AutoROICalc service token is never sent by the browser.

This plugin connects to the AutoROICalc service only after an administrator provides a service token and enables tracking.

* AutoROICalc: https://autoroicalc.com/
* Record API documentation: https://autoroicalc.com/docs/records/api/
* Terms of Service: https://autoroicalc.com/terms-of-service/
* Privacy Policy: https://autoroicalc.com/privacy-policy/

== Diagnostics and breakdowns ==

Settings -> Events Tracking includes a test event for checking server delivery. Debug mode adds an administrator diagnostics panel with detected, sent, and skipped event counts, consent state, and the latest REST status.

Tracked blocks can attach validated AutoROICalc breakdown JSON under `custom_data.breakdowns`. See the Record API documentation for the supported schema and limits.

== Frequently Asked Questions ==

= Do I need an AutoROICalc account? =

Yes. An AutoROICalc service token is required to send event records.

= Does WordPress store my AutoROICalc account password? =

No. During guided connection, the password is sent server-to-server to AutoROICalc and is not stored. The temporary regular account session is closed after a restricted installation token has been created.

= Is the service token visible in the page? =

No. Visitors send signed event data to WordPress. WordPress uses the service token for the server-to-server AutoROICalc request.

= Which WordPress blocks support click tracking? =

Button, Navigation Link, linked Image, Paragraph, Heading, and List Item blocks are supported. Paragraph, Heading, and List Item tracking applies to the links inside the block.

= Can I track an element that is not a supported block? =

Yes. Administrators can define custom CSS selector targets for click, hover, and viewport visibility events.

= Does the plugin support Elementor? =

Yes. Elementor Button, Icon List, Text Editor, Image, Heading, Icon, Icon Box, Image Box, and Call to Action widgets have native Event Tracking controls. Every rendered link in a multi-link widget creates its own target event. Elementor Pro Forms can add AutoROICalc Event under Actions After Submit to record validated submissions. Form values are excluded by default; administrators may explicitly allowlist selected non-sensitive field IDs for inclusion in raw record data.

= Can the plugin track new WordPress users? =

Yes. Enable WordPress user registration tracking under Settings -> Events Tracking. It supports registrations created by WordPress and WooCommerce and lets you configure the record type, description, tags, and captured or fixed sources. Account identity fields and WordPress user IDs are never sent.

= Can I override captured campaign sources? =

Yes. Choose Fixed source override in the Event Tracking block settings and enter up to six sources.

= Does source attribution connect to Google Analytics? =

No. The plugin uses UTM parameters and browser referrer information to derive source / medium values in a familiar analytics format. It does not load Google Analytics, use Google Analytics cookies, or read data from a Google Analytics account.

= How are repeated clicks counted? =

With the default 10-second debounce window, the first click is sent immediately and later clicks on the same target are ignored until the window expires. Debouncing can be changed globally and per target.

= Does the plugin use cookies? =

The plugin does not use long-lived attribution cookies. Captured source history uses local storage, optional debounce state uses session storage, and server-side Elementor Pro Form and user-registration tracking may use the `arc_consent` and `arc_sources` first-party session cookies described under Consent and data storage. Form values and account identity details are never stored in these cookies.

= Does the plugin collect form values or customer details? =

Not by default. Elementor Pro Form values are read only when an administrator explicitly allowlists their field IDs in the AutoROICalc Event action. Password, file-upload, CAPTCHA, and honeypot fields are always excluded. Site administrators are responsible for avoiding unnecessary personal or sensitive data and meeting applicable disclosure, consent, and retention requirements.

= Why was an event not sent? =

Check that tracking is enabled, the service token is configured, the target has tracking enabled, its record type and description are present, and its configured consent category has been granted. Debug mode and Send test event can provide additional delivery information.

= What happens to plugin data when the plugin is uninstalled? =

Settings and local connection data are retained by default so reinstalling the plugin does not discard the configuration. Administrators can enable uninstall cleanup under Data retention before uninstalling. Cleanup does not delete records already sent to AutoROICalc, remove tracking configuration embedded in Gutenberg and Elementor content, or revoke the installation token in AutoROICalc. The shared local service token is retained when AutoROICalc for WooCommerce is installed. Installation tokens can be revoked separately under Integrations in AutoROICalc.

== Changelog ==

= 1.4.0 =
* Added native Event Tracking controls for Elementor Icon List, Text Editor, Image, Heading, Icon, Icon Box, Image Box, and Call to Action widgets, with separate signed tracking for every rendered link.
* Added an enabled-by-default option to exclude logged-in administrator activity from front-end interactions, supported form events, and administrator-initiated registrations.
* Kept Dashboard report widgets and manual diagnostic test events available while administrator activity is excluded.

= 1.3.0 =
* Added a guided setup screen after plugin activation.
* Added server-side account connection that creates a separate scoped service token for the current WordPress installation.
* Added optional AutoROICalc account registration with explicit Terms acceptance and email-verification guidance.
* Added a state-aware setup checklist for event configuration, successful API delivery, and Dashboard reporting.
* Added a persistent setup checklist that can be hidden after every onboarding step is complete.
* Kept manual service-token and wp-config.php configuration available for existing installations and managed deployments.
* Added an opt-in uninstall cleanup policy for plugin settings and local connection data.
* Reorganized the settings screen into focused Setup, Event tracking, Dashboard widgets, Advanced, and Diagnostics views.
* Prevented stored service-token values from being written back into the settings-page HTML.
* Added configurable, privacy-conscious WordPress user-registration tracking without transmitting account identity fields or user IDs.
* Moved WooCommerce product-view, add-to-cart, and checkout-start tracking to the dedicated AutoROICalc for WooCommerce plugin.

= 1.2.1 =
* Added an opt-in Elementor Pro Form field allowlist for sending selected values under `raw_data.form.fields`.
* Kept form values excluded by default and always excluded password, file-upload, CAPTCHA, and honeypot fields.
* Added field-count and value-length limits plus server-side sanitization for selected form values.
* Documented the first-party session cookies used by server-side Elementor Pro Form tracking, including example privacy-policy wording.

= 1.2.0 =
* Added native Event Tracking controls to Elementor Button widgets.
* Added an AutoROICalc Event action for validated Elementor Pro Forms submissions.
* Added server-side Elementor form delivery with captured source / medium support and without reading submitted form fields.
* Added consent-category handoff for server-side form actions.
* Removed the service token from the AutoROICalc API request URL and send it only in the server-side authentication header.

= 1.1.0 =
* Added authenticated WordPress Dashboard rendering for configured AutoROICalc Data Value, Gauge, and Target report widgets.
* Added report, configured-widget, and dataset selectors with readable IDs and names.
* Added responsive, collapsible widget settings cards and clearer WordPress-styled controls.
* Added compact Data Value widget heights and consistent bordered value styling.
* Added loading indicators for report widgets, report catalogs, and dataset catalogs.
* Fixed WordPress.org readme rendering for the service-token and consent code examples.

= 1.0.1 =
* Added WordPress.org screenshot captions for the Dashboard report, global settings, report widgets, and block editor tracking controls.

= 1.0.0 =
* First public release of AutoROICalc Event Tracking.
* Added block editor click, hover, visibility, form, custom selector, WooCommerce, source/medium attribution, consent, diagnostics, breakdown, and authenticated Dashboard report widget support.

= 0.4.2 =
* Added an animated loading indicator while Dashboard report widgets are being prepared or refreshed.

= 0.4.1 =
* Fixed Dashboard chart refresh while preserving the strict iframe sandbox and authenticated server-side access.

= 0.4.0 =
* Added authenticated AutoROICalc report chart widgets for the WordPress administration Dashboard.

= 0.3.1 =
* Added an editor warning when a tracked block is consent-gated and explicit browser consent is required.

= 0.3.0 =
* Added form events, custom CSS selector targets, WooCommerce lifecycle events, engagement triggers, dwell timing, diagnostics, and signed context metadata.
