CQI Referrer Attribution

Most analytics plugins guess where your traffic came from by running a script in the visitor's browser, after the page has already loaded, and after any ad blocker or privacy extension has had a chance to block it. CQI Referrer Attribution classifies every visit on the server, before the page is even sent, so the data is complete and the plugin adds no client-side JavaScript, no extra request, and no Core Web Vitals penalty. It also answers a question most attribution tools still miss: how much of your traffic is coming from AI assistants. ChatGPT, Gemini, Perplexity, Claude, Copilot, and a growing list of others now send real visitors. This plugin classifies that traffic as its own channel, not lumped into Direct or Referral where it disappears. Nine channels are detected automatically: AI Tools, Organic Search, Social Media, Email, Paid Search, Paid Display, Campaign, Referral, and Direct. This plugin is fully functional with no licence key, trial period, or usage limit of any kind. AI Referrer Taxonomy A built-in registry of AI assistant domains is used to classify AI-referred traffic. The default set includes ChatGPT, Google Gemini, Perplexity, Claude, Microsoft Copilot, Grok, Meta AI, and more. Entries can be added, edited, activated, deactivated, deleted, and exported as JSON. Dashboard A 30-day summary showing total sessions, session change versus the previous 30 days, AI traffic sessions and their share of total traffic, top channel, and a channel share pie chart. Sessions log The full Sessions report supports date range, channel, and source filters, pagination, and CSV export. Consent-aware When CQI Consent is active, attribution is only persisted after marketing consent is granted. Without consent, classification runs in memory only and no cookie or database row is written. The plugin operates in permissive mode when CQI Consent is not installed. Independent of CQI Consent, the plugin reads the Global Privacy Control signal (the Sec-GPC HTTP header) on every request and does not persist attribution when it is present. This is checked regardless of whether any consent plugin is installed. When CQI Consent is not installed, the plugin also recognises marketing consent already withheld through Complianz or CookieYes, if either is active on the site, using each plugin's own consent cookie. Borlabs Cookie is not currently supported, since its consent cookie format is not publicly documented; sites running Borlabs Cookie alone currently operate in permissive mode, the same as a site with no consent plugin at all. Privacy by design No personal data is stored. Session tokens are HMAC-SHA256 hashes of an anonymized IP address (last octet zeroed) and the current date. Raw IP addresses are never written to disk. Token rotation is daily. The plugin is registered with the WordPress personal data export and erasure framework. Excluded channels Any channel can be excluded from the Dashboard summary, the channel share chart, and the Sessions report. This is most useful for removing Direct / Unknown from view so reports focus on traffic you can actually attribute and act on. Path exclusions and bot filtering A built-in guard silently drops requests to /robots.txt, /sitemap.xml, /xmlrpc.php, /favicon.ico, and other system paths before classification runs. Additional path prefixes can be added in Settings, one per line, to suppress noise from any crawlers or automated probes specific to your site. Public PHP API Two functions are available for use in themes and other plugins:

• cqip_attr_get_channel(), returns the current visitor's channel slug
• cqip_attr_get_source(), returns the full attribution array

These function names are intentionally preserved from CQIP Site Services v1.8.0 for backward compatibility on sites migrating from that plugin. Filter and action hooks These hooks let other plugins extend this plugin's behaviour. They are not used by this plugin itself; they exist for add-ons such as CQI Referrer Attribution Pro.

• cqi_referrer_attribution_logo_url (filter), the mark shown in the admin page header
• cqi_referrer_attribution_plugin_name (filter), the page title shown in the admin page header
• cqi_ra_session_logged (action), fires after each session is recorded, receives the new row's ID and data
• cqi_ra_admin_tabs (action), fires inside the admin page's tab navigation, after the built-in tabs
• cqi_ra_unknown_tab_handled (filter), fires when an unrecognized tab slug is requested, lets an add-on render its own tab body
• cqi_ra_sessions_view_filters (filter), the Sessions report's query filters, before the session log is queried; also applied before CSV export runs
• cqi_ra_sessions_filter_bar (action), fires inside the Sessions filter bar, after the built-in filter fields
• cqi_ra_sessions_table_header (action), fires inside the Sessions table header row, after the built-in columns
• cqi_ra_sessions_table_row (action), fires inside each Sessions table row, after the built-in columns, receives the row object
• cqi_ra_dashboard_log_id_in (filter), restricts Dashboard metrics to a specific list of session row IDs

1. Upload the cqi-referrer-attribution folder to /wp-content/plugins/.
2. Activate the plugin through the Plugins menu in WordPress.
3. Go to Attribution in the WordPress admin menu to view the Dashboard.

No configuration is required after activation. Classification begins on the next front-end page request.

1.8.0

• Added: Direct / Unknown sessions are now excluded by default from the Dashboard's Channel Share chart and summary cards, with a visible notice stating how many sessions were excluded and a one-click toggle to show them again. Direct/Unknown is usually the largest single channel and tends to visually swamp every genuinely interesting channel on a chart this size. This is a per-view, reversible default (a URL parameter, not a stored setting) — separate from the existing, permanent "excluded channels" setting on the Settings tab, which still applies underneath it and is never silently overridden by this toggle.
• Fixed during the same change: the Dashboard's summary cards and its pie chart computed their channel breakdown independently in two separate methods, which had no mechanism keeping them in agreement. Both now apply the same exclusion logic from a single source of truth.

1.7.0

• Added: CQI_RA_DB::get_channel_breakdown_for_period(), a public method returning a channel breakdown for an arbitrary date range. Not used by this plugin itself; added for an add-on (CQI Referrer Attribution Pro) that needs a previous-period channel breakdown to show attribution coverage change over time, which get_dashboard_metrics() does not provide on its own.

1.6.1

• Fixed: NotebookLM and DeepSeek, added to the default AI Referrer Taxonomy in 1.6.0, never appeared on any site that had already activated an earlier version. The seeding method only ever wrote defaults once, on first activation, by design, so user edits to the taxonomy would never be overwritten on update. New default domains added in a later release had no way to reach an existing install. Confirmed directly on a live v1.6.0 install showing 17 entries, not 19. The seeding method now additively adds any new default domain not already present in the stored taxonomy, on every page load, without touching, reordering, or reactivating any entry the operator already has.

1.6.0

• Added: NotebookLM (notebooklm.google.com) and DeepSeek (chat.deepseek.com) to the default AI Referrer Taxonomy, bringing the default set to 19 entries.
• Added: when CQI Consent is not installed, attribution now also recognises marketing consent already withheld through Complianz or CookieYes, using each plugin's own consent cookie. Borlabs Cookie is not yet supported; no public documentation of its consent cookie format was found. Sites running Borlabs Cookie alone continue to operate in permissive mode, the same as before this change.

1.5.1

• Fixed: both promotional banner SVGs (assets/banners/) had a root-level title element, which some mobile browsers render as a persistent floating tooltip on tap or focus rather than a hover-only tooltip, obscuring the banner image. Removed; the same descriptive text is now on an aria-label attribute instead, which does not trigger this rendering behaviour.

1.5.0

• Added: Global Privacy Control (Sec-GPC) support. When a visitor's browser sends this signal, a legally binding opt-out under CCPA/CPRA in California and recognised under similar laws in Colorado, Connecticut, and Virginia, attribution is not persisted for that request: the same outcome as withheld consent. Checked unconditionally, regardless of whether CQI Consent or any other consent plugin is installed, since this signal is binding independent of any site-side consent tooling.

1.4.2

• Fixed: panel and card subtitle text (.cqi-ra-panel__sub, .cqi-ra-card__sub) used #9CA3AF on white, measured at 2.54:1 contrast, well short of the WCAG AA 4.5:1 minimum for body text. Changed to #6B7280, the colour already used for secondary text throughout the rest of this stylesheet, which measures 4.83:1.

1.4.1

• Added: CQI_RA_DB::get_log_row_by_token(), a public method returning the most recent attribution log row for a session token, or null if none exists. Not used by this plugin itself; added for an add-on (CQI Referrer Attribution Pro) that needs to confirm real attribution exists for the current visitor before recording a conversion against it.

1.4.0

• Added: CQI_RA_DB::get_daily_sessions(), a public method returning session counts grouped by day and channel. Not used by this plugin itself; added for an add-on (CQI Referrer Attribution Pro) building trend charts and reports that need day-by-day data rather than the period summaries CQI_RA_DB::get_dashboard_metrics() already provides.

1.3.3

• Changed: refreshed the channel share chart's colour palette for the Organic Search, Social Media, Email, Paid Search, Paid Display, Campaign, and Referral channels. The previous set leaned muted and several adjacent slices were too close in hue to tell apart at a glance. AI Tools keeps its existing teal; Direct / Unknown stays neutral grey by design.

1.3.2

• Added: the cqi_ra_sessions_view_filters hook, already applied to the on-screen Sessions report, is now also applied to CSV export. Add-ons that filter the Sessions view (for example, a tag filter) now apply consistently to both the table and the exported CSV. No effect on this plugin's own behaviour; the hook has no listeners unless an add-on is active.

1.3.1

• Fixed: AI Taxonomy tab. Add, edit, toggle, delete, export, and reset all failed silently in the browser since the admin JavaScript had not been updated when the tab's markup was restyled. The JavaScript now matches the current markup throughout.
• Fixed: Reports tab CSV export ignored the on-screen date range and channel filter, since the export button read element IDs that no longer existed in the filter bar. CSV export now uses the same filters shown on screen.
• Removed: a leftover Conversions-view branch in the CSV export script, and an unreachable block of JavaScript referencing a white-label save feature that has no corresponding admin UI or AJAX handler in this plugin. Neither had any user-facing effect; both are gone.

1.3.0

• Added: a set of extension hooks (cqi_ra_session_logged, cqi_ra_admin_tabs, cqi_ra_unknown_tab_handled, cqi_ra_sessions_view_filters, cqi_ra_sessions_filter_bar, cqi_ra_sessions_table_header, cqi_ra_sessions_table_row, cqi_ra_dashboard_log_id_in) for the separate CQI Referrer Attribution Pro add-on. None of these change this plugin's own behaviour; they have no effect when nothing is listening to them.

1.2.3

• Fixed: corrected an oversized Upgrade Notice entry that exceeded the WordPress.org 300-character limit.
• Reverted uninstall.php variable names to the plugin's standard short-form prefix; the longer form tried in 1.2.2 did not change Plugin Check's output, since the underlying naming-convention check cannot be satisfied by any prefix declared inside the plugin itself.

1.2.2

• Plugin Check compliance: renamed global-scope variables in uninstall.php to the full plugin-specific prefix and completed rule-code documentation for the two schema-change queries it runs.
• Plugin Check compliance: shortened the readme short description to fit the WordPress.org 150-character limit.

1.2.1

• Fixed: removed the Conversions and Conversion Rate cards from the Dashboard. Both always read zero, since no conversion tracking exists in this plugin, and showing a permanently-zero metric was misleading.
• Added: AI Traffic Sessions card on the Dashboard, showing the session count and percentage of total traffic attributed to the AI Tools channel.

1.2.0

• Added: Excluded channels setting. Any channel, including Direct / Unknown, can now be removed from the Dashboard summary, the channel share chart, and the Sessions report, including CSV export.
• Added: uninstall.php now performs the Delete on uninstall action. Previously this setting had no effect; deleting the plugin never removed any data regardless of the setting.
• Fixed: removed two FAQ entries describing detection logic (GCLID/MSCLKID click ID parameters, a nine-step priority order) that did not match the plugin's actual classification behaviour. Replaced with an accurate description of the real priority order and UTM-based paid channel detection.
• Fixed: removed references to a conversion log feature from the Settings tab and readme. No conversion tracking exists in this plugin.
• Removed: nine unused internal methods and associated dead CSS left over from features that are not part of this plugin, with no functional impact.
• Documentation: added FAQ coverage for the CQIP Site Services compatibility guard, the new Excluded channels setting, and the Delete on uninstall behaviour. Documented two previously unlisted filter hooks. Rewrote the plugin description to lead with the practical benefit of server-side classification and AI traffic detection.

1.1.2

• Plugin Check compliance: renamed the licence management bootstrap function, its global variable, and three custom hook names to use the full plugin-specific prefix, resolving the remaining naming convention warnings. No functional change; internal identifiers only.

1.1.1

• Plugin Check compliance: documented justification for WordPress core's own escaped insert API being flagged as a direct database call.
• Plugin Check compliance: completed database query documentation pass.
• Documented the plugin's naming prefix convention and the reasoning behind it for ongoing maintenance reference.

1.1.0

• Fixed: free tier no longer stops recording sessions once 30 rows accumulate. Free now records the full 30-day history, matching the existing 30-day prune schedule, so dashboard reports are accurate regardless of traffic volume.
• Fixed: the Sessions list label now correctly describes the 30-row list as a display limit, separate from the full 30-day reporting window.
• Added: Clear Attribution Log is now available on the free tier (previously Pro-only), giving free users a manual reset option.

1.0.12

• Plugin Check compliance: restructured remaining multi-line database queries to single-line statements so compliance documentation is correctly associated with each query by automated review tools.
• Plugin Check compliance: completed full documentation pass across all direct database queries.

1.0.11

• Plugin Check compliance: completed database query review with explicit justification documentation for every direct query, confirming all table references originate from trusted internal sources.
• Plugin Check compliance: replaced remaining integer type casts with WordPress's dedicated integer sanitization function for all page and period parameters.

1.0.10

• Plugin Check compliance: dashboard chart library is now bundled with the plugin instead of loaded from an external network resource.
• Plugin Check compliance: hardened database queries so table name references are always escaped at the source.
• Plugin Check compliance: corrected internal variable naming to consistently use the plugin's own prefix.
• Plugin Check compliance: documented and resolved output escaping checks across the dashboard and print report.

1.0.9

• Adjusted internal file structure for licence management to meet hosting platform compliance requirements.

1.0.8

• Plugin Check (PCP) compliance pass: replaced parse_url() with wp_parse_url() throughout.
• Plugin Check: added wp_unslash() to all $_GET, $_POST, and $_SERVER reads before sanitisation, across the classifier, admin, report, and white-label classes.
• Plugin Check: removed load_plugin_textdomain() call — WordPress.org auto-loads translations for hosted plugins since WordPress 4.6.
• Plugin Check: documented justification for in-memory CSV stream handling (php://memory is not a filesystem path; WP_Filesystem does not apply).
• Plugin Check: documented justification for table-name SQL interpolation in the database class — table names originate exclusively from $wpdb->prefix, never from user input; all user-supplied values use $wpdb->prepare() placeholders.

1.0.7

• Updated licence management SDK to latest release.
• Confirmed compatibility with WordPress 7.0.

1.0.6

• Uninstall: moved cleanup logic from uninstall.php to the licence management after_uninstall hook. Delete on uninstall behaviour is unchanged.

1.0.5

• Accessibility: resolved nine WCAG 2.1 AA contrast failures across admin UI and print report. Active tab, primary button, and period selector now use dark text on teal background (8.19:1). Teal text on white replaced with accessible variant #0A8078 (4.80:1). Muted informational text lifted from #9CA3AF to #6B7280.
• Accessibility: added :focus-visible styles to all interactive elements — inputs, buttons, period pills, channel tabs, drill-down controls.
• Accessibility: added aria-label to hidden file import input.

1.0.4

• Storage: free tier row cap (30 rows) now enforced at insert time, preventing log table bloat on busy sites.
• Storage: landing_url column changed from TEXT to VARCHAR(500) for more efficient storage. Database schema version updated.
• Settings: added Data and Storage panel with Delete data on uninstall option (all tiers). When enabled, plugin deletion removes all tables and options cleanly.
• Added uninstall.php — drops attribution and conversion tables and removes all plugin options when Delete data on uninstall is enabled.

1.0.3

• Attribution panel moved to top-level WordPress admin menu (Settings > Referrer Attribution is now Attribution in the sidebar).
• Classifier: extended built-in system path guard to cover /robots.txt, /sitemap.xml, /favicon.ico, /.well-known/, and additional WordPress entry points.
• Settings: added Path Exclusions field — one path prefix per line, applied before classification runs.
• Settings: surfaced Self-Referral Exclusions field — shows the auto-excluded site domain and accepts additional domains (staging, subdomains) one per line.

1.0.2

• Classifier: added early-exit guard for xmlrpc.php, wp-cron.php, wp-signup.php, and wp-activate.php requests. Bot probes targeting these endpoints no longer appear in the session log.

1.0.1

• Licence management configuration updated to reflect dedicated product website.
• Admin page footer added: CQIP ecosystem attribution line.
• Pro upgrade prompt copy updated — removed third-party library name.
• Noop upgrade URL updated to referrerattribution.com/pro/.
• British English corrected in code comments.

1.0.0

• Initial standalone release.
• Nine-channel classification engine.
• AI Referrer Taxonomy with 17 default entries.
• Dashboard with summary cards and four charts (Pro).
• Period selector — 7, 30, 90 days (Pro).
• Channel drill-down to source level (Pro).
• Sessions log with filters and CSV export (Pro for full access).
• Conversions log with filters and CSV export (Pro).
• Print / PDF report — opens a formatted browser print view, no server-side library required (Pro).
• White-label branding configuration (Pro).
• Consent gate for CQI Consent integration.
• GDPR personal data export and erasure hooks.
• WP-Cron daily log pruning.
• License management and Pro upgrade flow integrated.