=== XPmetric Bot Tracker ===
Contributors:
Tags: analytics, bot, crawler, statistics, web analytics
Requires at least: 6.0
Tested up to: 7.1
Stable tag: 1.1.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Report likely AI crawler requests to XPmetric. Human analytics script injection is optional and off by default.

== Description ==

XPmetric Bot Tracker reports likely crawler requests that reach WordPress and can optionally add XPmetric's browser analytics script to public pages.

Bot reporting and human analytics are separate settings. Bot reporting sends likely crawler hits to XPmetric for classification. Optional human analytics uses either the cookieless script (`p.js`) or cookie-mode script (`p.cookie.js`); this setting defaults to off and is separate from bot reporting.

An XPmetric account with an active trial or subscription is required for event ingestion. Create a site and find its site token in [XPmetric](https://xpmetric.com/) under **Settings → Sites → Get Script**. See the [XPmetric Privacy Policy](https://xpmetric.com/privacy) and [Terms of Service](https://xpmetric.com/terms) for information about the service.

= Data sent to XPmetric =

When bot reporting is enabled, the plugin sends a JSON request to XPmetric for requests that pass its loose user-agent and page-path checks. The bot payload contains the site token, the full requested URL, path, referring URL, request user-agent, and HTTP response status. The plugin does not send a separate IP field in this JSON payload. XPmetric receives the HTTP connection and may use connection metadata to derive country; see the service privacy policy for its handling of that data.

The XPmetric API classifies known crawlers and normalizes URL fields before storing a hit. It stores the page origin and path with supported UTM parameters, stores a canonical path without the query string, and keeps only the referrer origin. Other query parameters and URL fragments are not retained in the normalized page URL. Requests to recognized authentication and credential routes are not recorded.

When optional human analytics is enabled, the selected external script sends page and event data to XPmetric, including the site token, normalized page URL and path, referrer origin, supported UTM parameters, screen dimensions, browser language, and event details. Cookie mode also uses a first-party visitor cookie and session storage and sends visitor and session identifiers. Cookieless mode does not write visitor or session identifiers to browser storage.

The cookie-mode script may require visitor consent depending on the site's visitors and applicable rules. This plugin does not include a consent banner or consent-manager integration. It adds the selected script directly to the page; configure an existing consent manager to hold the script until analytics consent where needed, or leave human analytics injection off and add the script through that manager.

== Installation ==

1. Create an XPmetric account, add a site, and copy its site token from **Settings → Sites → Get Script**. An active trial or subscription is required for event ingestion.
2. In WordPress, go to **Plugins → Add New Plugin → Upload Plugin**, upload the XPmetric Bot Tracker ZIP, install it, and activate it.
3. Open **Settings → XPmetric Bot Tracker**, enter the site token, and save.
4. Enable **Enable bot tracking** to report likely crawler requests. Use **Send test hit** to check the connection.
5. Human analytics is optional and defaults to off. To enable it, turn on **Inject tracking script in the site head**, choose the mode that matches this site in XPmetric under **Settings → Sites → Site**, then save. Changing this mode changes the browser script URL; it does not change the XPmetric site setting.
6. Before enabling human analytics, remove other XPmetric browser tags. The plugin checks WPCode and the public home-page response before enabling its own tag.
7. If you use cookie mode and require analytics consent, configure your consent manager to delay loading this script until consent. The plugin does not perform this gating itself.

The optional page-cache fallback instructions are shown on the plugin settings page. They apply to PHP page caches that can exit before normal WordPress plugins load.

== Frequently Asked Questions ==

= Does this plugin require an XPmetric account? =

Yes. Create a site in XPmetric and enter its site token in the plugin settings. XPmetric requires an active trial or subscription to ingest events. When event ingestion is inactive, the service does not accept new bot or human analytics events.

= Is the human analytics script required for bot reporting? =

No. Bot reporting uses PHP and is controlled by **Enable bot tracking**. Human analytics uses a separate switch and defaults to off.

= What does the plugin send for bot reports? =

It sends the site token, full requested URL, path, referring URL, request user-agent, and HTTP response status to the configured crawler endpoint. The default endpoint is `https://xpmetric.com/api/crawler`. The service classifies known crawlers and normalizes page URL, path, and referrer fields before storing the hit. See **Data sent to XPmetric** above and the [XPmetric Privacy Policy](https://xpmetric.com/privacy).

= Does the plugin store the full URL and referrer sent by the bot reporter? =

The plugin sends the request URL and referring URL as received by WordPress. The XPmetric API normalizes those fields before storage: the page URL retains its origin, path, and supported UTM parameters, while the referrer is reduced to its origin. Other URL query parameters and fragments are not retained in the normalized page URL.

= Does this plugin provide a consent banner or gate cookie mode? =

No. The plugin adds the selected browser script directly to each public page and does not wait for a consent manager. If your site uses cookie mode and needs analytics consent, configure your existing consent manager to load the script only after consent, or keep this plugin's human analytics switch off and add the script through your consent manager.

= Which human analytics mode should I choose? =

Choose the same mode shown for the site in XPmetric under **Settings → Sites → Site**. Cookieless mode loads `https://xpmetric.com/p.js`; cookie mode loads `https://xpmetric.com/p.cookie.js`. Switching modes here changes the URL used by the plugin but does not update the XPmetric site setting.

= Why does the plugin check the home page before enabling human analytics? =

The check looks for an existing XPmetric browser script in WPCode and in the public home-page response to reduce duplicate pageviews. If WordPress cannot verify the page response, the plugin leaves its own human analytics injection off. Remove an existing tag or resolve the scan problem, then save again.

= Does the crawler reporter identify every bot? =

No. The plugin uses a loose user-agent prefilter so likely crawlers can be reported without maintaining a server-side bot catalog. XPmetric performs the final classification of known crawler user-agents; unknown or unrecognized user-agents may not be recorded.

= Where are plugin settings stored? =

Settings are stored in the WordPress options table. Uninstalling the plugin removes its settings.

== Screenshots ==

1. Configure bot reporting and optional human analytics in WordPress.

== Upgrade Notice ==

= 1.1.0 =
Optional human analytics is off by default. Existing bot tracking settings are preserved.

== Changelog ==

= 1.1.0 =
* Added optional, opt-in human analytics injection with cookieless and cookie modes.
* Added duplicate-script checks for WPCode and the public home page.
* Kept bot reporting separate from human analytics and preserved crawler status reporting and the PHP page-cache fallback.

= 1.0.0 =
* Initial release of XPmetric Bot Tracker with crawler reporting, connection diagnostics, and a PHP page-cache fallback.
