WordPress Plugin

The plugin records AI crawler visits on requests that reach WordPress and uses a browser script to collect human referrals from AI answers. Events are saved locally and delivered to Airefs through WP-Cron and a protected background runner. Once it’s active, connected, and scheduled events are running, Impressions and Clicks can populate in your dashboard.

Installing the plugin

1. Log in to your WordPress admin dashboard.
2. Go to Plugins → Add New Plugin.
3. Search for Airefs.
4. Click Install Now, then Activate.

Alternatively, download AI Search Analytics & Tracking and upload it via Plugins → Add New → Upload Plugin.

Connecting your account

After activation, go to Settings → Airefs Tracking in your WordPress admin. Copy your Access Token from your Airefs account’s settings, enter it in the plugin’s Access Token field, and click Save Settings. Keep Enable Tracking selected.

The plugin begins collecting pageviews once connected. Queued events still need background delivery and processing before they appear in Airefs.

A note on caching plugins

AI crawler tracking needs the request to reach WordPress. A CDN or static page cache that serves a response before PHP runs prevents the server tracker from observing that request. If your site uses such a cache, configure an appropriate cache bypass for crawler requests or collect events at that layer through the HTTP API integration.

Cached HTML can still collect human clicks through the browser script, provided the cached page contains the tracker and its WordPress REST endpoint is reachable. The plugin includes WP Rocket user-agent exclusions and optional LiteSpeed handling; this does not guarantee coverage through every cache configuration. Clear page caches after updating the plugin or changing its settings, then verify tracking on both cached and uncached pages.

Background delivery

Page requests save events to the site’s database. Background workers send them to Airefs later in small batches to reduce network requests, so page handling does not wait for the analytics API. Each event stays in the queue until Airefs confirms that it has stored it; partial batch failures leave unconfirmed events queued. Temporary failures are retried with increasing delays, and stable event IDs prevent retries from being counted twice in reports. Pending events do not expire. Local queue writes, the footer script, and its browser request still use resources.

WP-Cron schedules delivery, and a protected background runner provides another way to start from site requests and continue processing a backlog. Hosting restrictions can stop both mechanisms. For low-traffic sites or disabled WP-Cron, ask your host to run WordPress scheduled events at least once a minute and allow loopback requests. A stopped scheduler delays saved events; delivery resumes after the scheduler or background runner recovers.

Check Settings → Airefs Tracking → Background delivery for pending events, the oldest event, last attempt, last confirmed delivery, errors, and storage use. Retry delivery requests a background retry. A successful connection test is not a delivery receipt; the confirmed-delivery time shows actual progress.

Queue storage defaults to 64 MiB across the WordPress network, with a 100,000-event safety limit. A full or unavailable database cannot accept new events. The browser endpoint returns an error and the plugin records a rejection when the database is available; already saved events are retained. Address delivery errors before the queue fills. Hosts can adjust the storage budget through the airefs_tracking_queue_capacity_bytes filter.

Disabling tracking or deactivating the plugin pauses delivery and keeps pending events. A replacement token can resume them only after verifying the same Airefs site at the same endpoint. Events from a different or unverified connection stay blocked: restore the previous token and endpoint to deliver them. Changing accounts never transfers the backlog. Deleting the plugin through WordPress uninstall removes the local queue, including undelivered events.

If you use a reverse proxy, configure the trusted proxy and web server to set WordPress’s REMOTE_ADDR to the visitor’s address. Otherwise, visitor IP and the browser endpoint’s rate limit can reflect the proxy rather than individual visitors. The plugin does not accept arbitrary forwarded IP headers as visitor identity.

The server tracker captures PHP’s response status at shutdown for requests that reach WordPress; it cannot observe responses served entirely by an upstream cache. The browser API supports AirefsTracking.trackPageView() and AirefsTracking.trackEvent("pageview"); other custom event names return false without sending an event.

WordPress relays browser events through its server, so its outbound connection does not identify the visitor’s country. These click records use an unknown country rather than the hosting server’s location.

The site’s local queue holds visitor IP addresses, User-Agent strings, and session IDs until confirmed delivery. Pending data can remain indefinitely during an outage or while tracking is paused; WordPress uninstall removes it. The API anonymizes non-bot IP/User-Agent values before persisting analytics records; bot records may retain them for attribution and validation. Queued page URLs retain origin, path, validated WordPress page IDs, explicitly configured content parameters, and supported UTM parameters. Other query parameters and fragments are removed; URLs containing credentials are rejected. Referrers retain only origin and path.

Pages identified by query parameters

Valid p and page_id values are preserved automatically, so /?p=123 and /?p=456 appear as separate pages in crawler and click reports. These IDs must be positive decimal numbers of at most 20 digits; leading zeros are removed.

For other content selectors, open Settings → Airefs Tracking → Advanced Settings → Content Query Parameters. Enter comma-separated names such as countries to distinguish /jobs?countries=201 from /jobs?countries=202. Each WordPress site has its own setting. Names are case-sensitive; up to 16 custom names are allowed. Configure only parameters whose values are safe to send to analytics. Known credential, session and tracking parameter names remain blocked even if entered.

Content parameter values must be nonempty, contain no control characters and fit within 200 UTF-8 bytes. Duplicate query names are discarded. Remaining content parameters are sorted and encoded consistently; a content query over 2,048 encoded bytes is discarded. UTM parameters remain separate attribution fields and do not create separate pages. URL fragments remain excluded.

Settings changes apply to newly captured events. Queued events keep their original settings through retries. Historical data and older queued events cannot recover query values that have already been removed. Roll out the updated Airefs API before this plugin version to enable query-aware reports.