Metrics

An effective on-site search implementation provides unique insight into your visitors. By observing what visitors are searching for you can make educated decisions about areas of improvement when it comes to your content.

SearchWP’s Metrics extension collects comprehensive data for on-site search, and provides you with actionable advice about refinements you can make to your content as time goes on.

SearchWP Metrics main interface

Watch Video

Installation & Setup

Metrics was built to be a turnkey Extension for SearchWP. Metrics is a standalone WordPress plugin that should be installed and activated alongside SearchWP itself. Once installed and activated Metrics will immediately begin tracking searches and clicks. Metrics will begin displaying data as soon as enough has been collected.

Metrics was designed to supersede SearchWP’s core statistics feature. As a result, both the SearchWP Statistics page and Dashboard Widget will no longer display, and counterparts from Metrics will take their place.

Click Tracking

By default, Metrics will automatically track clicks for the Default engine, assuming that your search results template uses The Loop. Any link within The Loop that is generated using get_permalink() (or variant thereof) will automatically be set up for click tracking. If you’re using a standard search results template you should be all set without needing to make any edits.

To integrate click tracking in your supplemental engine(s) you need to add two Hooks to your results template, one before your own loop of results, and one afterward.

Begin Metrics link tracking:

	<?php

	// Initiate Metrics link tracking
	do_action( 'searchwp_metrics_click_tracking_start' );

view raw functions.php hosted with ❤ by GitHub

Stop tracking links:

	<?php

	// Stop Metrics link tracking
	do_action( 'searchwp_metrics_click_tracking_stop' );

view raw functions.php hosted with ❤ by GitHub

All links generated with get_permalink() (or variant thereof) within those two actions will be processed by the click tracking within Metrics.

Metrics ships with its own Dashboard Widget that allows you to take a quick look at basic data when you log in to your site.

SearchWP Metrics Dashboard Widget

The Widget updates in real time as you visit your Dashboard, and you can customize the number of popular searches and number of popular posts shown.

Customizing Data

Metrics allows you to easily customize the data being displayed. You can control the date range, the search queries, and the engines to display:

Customize what Metrics displays

Date Range: Customize the date range shown in the main chart and engine details.

Search Query Controls: Limit the data displayed to a set of search queries. You can also control what queries have been ignored.

Engines to Display: Control which engine(s) are displayed in the charts

Reviewing Data

The line chart at the top of the page shows the searches over the chosen time frame for each selected engine. Below are details for each engine that provide specific metrics for further examination:

Screenshot of engine details from Metrics

Details for one of the chosen engines

A details area is shown for each selected engine.

Engine Statistics

On the left are Engine Statistics:

Total Searches: The total number of searches for the chosen time frame
No Results Searches: The total number of searches that generated zero results (click the icon for more details)
Total Results Viewed: The total number of conversions (clicks) for the chosen time frame
Searches Per User: The average number of searches per user (based on only users who have searched)
Clicks Per Search: The average number of clicks per search
Average Click Rank: The average rank of a clicked search result

When clicking the icon next to the No Results Searches you’re able to review a list of all of the search queries that yielded zero results, and how many searches there were. This list can be reviewed for accuracy as time goes on.

Screenshot of failed searches within Metrics

A list of no results searches within Metrics

Clicking the × icon next to a failed search query will add it to the list of ignored searches.

Insights

Metrics not only collects this data for you but it also implements some analysis to let you know where your content can potentially be improved. By analyzing conversion rates, popular searches, frequency of searches, and results rank positions, Metrics can let you know when:

Content is ranking low but getting a lot of clicks: can this content be optimized to rank higher?
Content is getting a high conversion rate: should this content be more prominently linked because so many visitors are searching for it?
Searches are converting on a variety of posts: should new content be created for these search queries?

Insights can call out some areas of improvement based on actual visitor searches:

Insights give actionable advice based on collected data

Exporting Data

Within each engine details pane you can export any of the data being displayed:

Screenshot of the various export options in Metrics

The export features in Metrics

Exports are formatted as CSV files, which can then be used in any way you’d like.

Settings

Metrics integrates some shortcuts and settings that can help you customize things a bit.

Settings menu in Metrics

You can use Clear Metrics Data to remove the data logged by Metrics, and Remove All Ignored Queries will reset your ignored queries leaving nothing ignored. These operations cannot be undone so make sure you have a backup if necessary!

Modify Logging Rules

Metrics comes with some basic controls to make excluding certain searches a bit easier:

Easily blacklist User IDs/Roles or IPs to prevent searches from being logged

Here you can add any combination of WordPress User IDs or Roles that should have their searches ignored. You can also maintain a list of IPs to blacklist as well. This makes excluding internal searches (so as to avoid polluting data) a bit easier.

General Settings

There are a couple of general items to consider when using Metrics:

General settings for Metrics

Metrics is able to use its tracking data to provide a buoy of sorts for search results. If you’d like results with more clicks to rank higher over time than those with fewer clicks, you can tick the checkbox to Influence search results using click data. This feature requires SearchWP version 2.9.14 or higher.

Metrics can also clean up after itself. With the Remove all Metrics data on uninstallation checkbox ticked, Metrics will remove its custom database tables, all click tracking data, and any stored options upon deletion.

Filters

There are a couple of filters to note when using Metrics:

searchwp_metrics_dashboard_widget_max_popular_posts
Set the number of popular posts to show in the Dashboard Widget. Default is 5, to customize:

	<?php

	// Show 10 popular posts in the Metrics Dashboard Widget
	add_filter( 'searchwp_metrics_dashboard_widget_max_popular_posts', function( $limit ) {
	return 10;
	} );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_dashboard_widget_max_popular_searches
Set the number of searches to show in the Dashboard Widget. Default is 5, to customize:

	<?php

	// Show 10 popular searches in the Metrics Dashboard Widget
	add_filter( 'searchwp_metrics_dashboard_widget_max_popular_searches', function( $limit ) {
	return 10;
	} );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_click_param
Customize the URL parameter used for click tracking. Default is swpmtx, to customize:

	<?php

	// Customize the search parameter used by click tracking in Metrics
	add_filter( 'searchwp_metrics_click_param', function( $param ) {
	return 'myparam';
	});

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_redirect_tracking
Control whether Metrics redirects away from the tracking URL once a click has been tracked. Default is true, to customize:

	<?php

	// Prevent Metrics from redirecting away from click tracking URL
	add_filter( 'searchwp_metrics_redirect_tracking', '__return_false' );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_normalize_logged_searches
Control whether Metrics normalizes search queries before logging them. Default is true, to customize:

	<?php

	// Prevent Metrics from normalizing queries before logging
	add_filter( 'searchwp_metrics_normalize_logged_searches', '__return_false' );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_capability
Customize the capability required to view Metrics data. Default is publish_posts, to customize:

	<?php

	// Limit Metrics data to those who can manage_options
	add_filter( 'searchwp_metrics_capability', function( $capability ) {
	return 'manage_options';
	});

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_override_stats
Control whether Metrics overrides SearchWP’s core statistics. Default is true, to customize:

	<?php

	add_filter( 'searchwp_metrics_override_stats', '__return_false' );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_click_buoy
Control whether Metrics applies its data to the search algorithm. This can also be controlled in the settings. Default is false, to customize:

	<?php

	// Tell Metrics to influence search results by giving weight to posts with a higher conversion rate
	add_filter( 'searchwp_metrics_click_buoy', '__return_true' );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_skip_uid
Metrics uses anonymous IDs to track clicks. Use this hook to prevent the generation of these IDs. Default is false, to customize:

	<?php

	// Prevent UID generation in Metrics
	add_filter( 'searchwp_metrics_skip_uid', '__return_true' );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_cookie_name
Control the cookie name used by Metrics to track clicks. Default is swpext86386, to customize:

	<?php

	// Customize the cookie name used by Metrics
	add_filter( 'searchwp_metrics_cookie_name', function( $name ) {
	return 'clicky24';
	});

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_uid_expiration
Control the duration of the cookie (i.e. define the click tracking session length). Default is time() + WEEK_IN_SECONDS, to customize:

	<?php

	// Tell Metrics to consider a session length to be one day
	add_filter( 'searchwp_metrics_uid_expiration', function( $length ) {
	return time() + DAY_IN_SECONDS
	});

view raw functions.php hosted with ❤ by GitHub

searchwp_admin_bar
Control whether Metrics displays its Admin Bar entry. Default is true, to customize:

	<?php

	// Prevent Metrics Admin Bar entry
	add_filter( 'searchwp_admin_bar', '__return_false' );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_log_search
Control whether Metrics logs this search. Default is true, to customize:

	<?php

	// Customize whether Metrics logs this search
	add_filter( 'searchwp_metrics_log_search', function( $log, $engine, $query, $hits ) {

	// $log is whether or not to log the search
	// $engine is the engine being used for the search
	// $query is the search query
	// $hits is the number of results found for this search

	return $log;
	}, 10, 4 );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_prevent_core_stats_log
Control whether SearchWP’s core statistics feature logs this search. Default is false, to customize:

	<?php

	// Prevent logging in core SearchWP's core statistics when Metrics is running
	add_filter( 'searchwp_metrics_prevent_core_stats_log', '__return_true' );

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_default_start_date
Control the default start date (as a strtotime()-compatible string) when viewing Metrics. Default is '30 days ago', to customize:

	<?php

	// Have the default start date for Metrics be one week ago
	add_filter( 'searchwp_metrics_default_start_date', function( $start ) {
	return '7 days ago';
	});

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_default_end_date
Control the default end date (as a strtotime()-compatible string) when viewing Metrics. Default is 'now', to customize:

	<?php
	// Have the default end date for Metrics be one week ago

	add_filter( 'searchwp_metrics_default_end_date', function( $start ) {
	return '7 days ago';
	});

view raw functions.php hosted with ❤ by GitHub

searchwp_metrics_first_day_of_week
Control the first day of the week when viewing the date picker in Metrics. Default is 0, to customize:

	<?php

	// Customize the date picker in Metrics to have weeks start on Monday (zero-based index)
	add_filter( 'searchwp_metrics_first_day_of_week', function( $start ) {
	return 1;
	});

view raw functions.php hosted with ❤ by GitHub

Changelog

1.4.6

[Fix] Regression in the previous release that caused a MySQL error on initial table creation

1.4.5

[New] New option to automatically delete Metrics data older than a specified interval
[Improvement] Metrics data in the administration area is loaded incrementally to avoid server timeouts
[Improvement] New date picker with preset date ranges
[Improvement] Reduced Metric values to only two digits after the decimal point, for improved readability
[Improvement] Various UX improvements on some controls and modal panels
[Improvement] Reduced assets file size
[Notice] This release removes the Metrics metadata table. If you would like to retain this data: BACK UP the existing table before updating

1.4.4

[Fix] Malformed Blocklist causes PHP error
[Update] Translation files

1.4.3

[Fix] Error in PHP versions prior to 7.3 caused by a function call trailing comma
[Fix] MySQL error in the dashboard widget if Metrics has ignored queries
[Fix] "Remove All Ignored Queries" menu command doesn't work with SearchWP v4
[Fix] Blocking search query logging by user ID doesn't work
[Fix] Deprecation notices on PHP 8.2

1.4.2

[New] Option to delete all the data Metrics has logged before a specific date
[Change] Enhanced menu integration with modern versions on SearchWP
[Fix] Required parameter error when instantiating \SearchWP_Metrics\Search class with a limited set of arguments

1.4.1

[Fix] Handling of ignored queries with special characters

1.4.0

[New] Ability to manually ignore (with * wildcard support)
[Improvement] Bundler
[Update] Dependencies
[Update] Updated updater

1.3.2

[Fix] SearchWP 4 compatibility fix when displaying some reports

1.3.1

[NOTICE] The metadata table schema has been updated to be more capable. This update involves dropping and recreating the table. If you would like to retain this data: BACK UP the existing table before updating. Note that the data has not been used in Metrics to date, but you may have opted in to using it on your own since the introduction of the metadata table. This will be the final update to the metadata table schema. Metrics will be including additional reports based on metadata in future releases. If you are updating from version 1.2.4 or lower, there is nothing for you to do.
[Change] Metadata table schema update
[New] New filter searchwp_metrics_meta_origin_use_id to log the referer ID instead of referer URL
[New] New action searchwp_metrics_search_meta fired when a search is performed

1.2.8

[Fix] Error when SearchWP 4 is not active
[Fix] Warning when SearchWP is not active

1.2.7

[Fix] Permalink output when click tracking is enabled
[Fix] Dashboard Widget display when using SearchWP 4

1.2.5

[Fix] Omission of redundant core Stats links when using SearchWP 4
[Fix] Handling of ignored queries when using SearchWP 4
[Fix] Removes case sensitivity for Roles in blocklist
[New] Adds meta table for storing metadata
[New] Action searchwp_metrics_search when a search is run

1.2.4

[Fix] Redundant URL encoding
[Fix] Redundant Search Stats Dashboard link from core SearchWP Statistics feature
[Fix] Click buoy SearchWP 4 compatibility
[Update] Updated updater

1.2.3

[Fix] SearchWP 4 integration issue

1.2.0

[New] Adds SearchWP 4 compatibility

1.1

[New] No Results details can now be exported
[Improvement] When viewing Popular Search Details, click data is now included in export
[Fix] Incorrect date range when viewing Popular Search Details
[Fix] Expected behavior when overriding core SearchWP Statistics
[Update] Link to documentation for Synonyms
[Update] Dependencies
[Update] Updated updater

1.0.9

[New] Added additional parameters hits_min, hits_max when retrieving popular search queries over time
[Fix] Relocates hooks to make them more accessible to plugins
[Fix] False positive when preventing duplicate click tracking

1.0.8

[Improvement] Improved performance both when searching and viewing data

1.0.7

[New] New filter searchwp_metrics_dashboard_widget to control whether the Dashboard Widget is displayed

1.0.6

[New] New filter searchwp_metrics_redirect_status to modify the Status of click tracking redirects
[New] Chosen engines are now persisted and the defaults for the next viewing of Metrics
[Fix] Automatically recreate database tables should they be lost (e.g. after moving a site)
[Fix] Fixed an issue where some options were not removed during uninstallation (if that option is enabled)
[Fix] Fixed an issue preventing click tracking with customized query parameters

1.0.4

[Fix] Fixes an issue that prevented the uninstallation routine from running when enabled

1.0.3

[Improvement] Improves performance when generating Insights
[New] Settings button now has its own capability
[New] New filter searchwp_metrics_capability_settings to modify the Settings button capability

1.0.2

[Fix] Fixes PHP Notice for division by zero in certain circumstances

1.0.1

[Fix] Fixes PHP Notice in Dashboard Widget when no data has been recorded
[Fix] Fixes Fatal Error when SearchWP is not activated but Metrics is activated
[Fix] Fixes Fatal Error due to case sensitivity of Events directory

1.0

Initial release

Documentation – Table of Contents

Installation & Setup

Click Tracking

Dashboard Widget

Customizing Data

Reviewing Data

Engine Statistics

Popular Searches

Insights

Exporting Data

Settings

Modify Logging Rules

General Settings

Filters

Changelog

1.4.6

1.4.5

1.4.4

1.4.3

1.4.2

1.4.1

1.4.0

1.3.2

1.3.1

1.2.8

1.2.7

1.2.5

1.2.4

1.2.3

1.2.0

1.1

1.0.9

1.0.8

1.0.7

1.0.6

1.0.4

1.0.3

1.0.2

1.0.1

1.0

Create a Better WordPress Search Experience Today