Description
This plugin captures real user metrics about what elements are displayed on the page across a variety of device form factors (e.g. desktop, tablet, and phone) in order to apply loading optimizations which are not possible with WordPress’s current server-side heuristics.
This plugin is a dependency which does not provide end-user functionality on its own. For that, please install the dependent plugin Image Prioritizer or Embed Optimizer (among others to come from the WordPress Core Performance team). There are currently no settings and no user interface for this plugin since it is designed to work without any configuration.
Your site must have the REST API accessible to frontend visitors since this is how metrics are collected about how a page should be optimized.
Please refer to the full plugin documentation for a technical introduction, filter/action hooks, and extensions that show use cases and examples.
Installation
Installation from the directory within WordPress
- Visit Plugins > Add New in the WordPress Admin.
- Search for Optimization Detective.
- Install and activate the Optimization Detective plugin.
Manual installation
- Download the plugin ZIP from WordPress.org or, after following the Getting Started instructions, create a ZIP build from a clone of the GitHub repo via
npm run build:plugin:optimization-detective --env zip=true
. - Visit Plugins > Add New Plugin in the WordPress Admin.
- Click Upload Plugin
- Select the
optimization-detective.zip
file on your system from step 1 and click Install Now. - Click the Active Plugin button.
FAQ
-
Where can I submit my plugin feedback?
-
Feedback is encouraged and much appreciated, especially since this plugin may contain future WordPress core features. If you have suggestions or requests for new features, you can submit them as an issue in the WordPress Performance Team’s GitHub repository. If you need help with troubleshooting or have a question about the plugin, please create a new topic on our support forum.
-
Where can I report security bugs?
-
The Performance team and WordPress community take security bugs seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.
To report a security issue, please visit the WordPress HackerOne program.
-
How can I contribute to the plugin?
-
Contributions are always welcome! Learn more about how to get involved in the Core Performance Team Handbook.
The plugin source code is located in the WordPress/performance repo on GitHub.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Optimization Detective” is open source software. The following people have contributed to this plugin.
Contributors“Optimization Detective” has been translated into 3 locales. Thank you to the translators for their contributions.
Translate “Optimization Detective” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.0.0-beta1
Enhancements
- Add site health check to detect blocked REST API and short-circuit optimization when unavailable. (1762)
- Allow extensions to opt in to using the web-vitals attribution build via the
od_use_web_vitals_attribution_build
filter. (1759) - Disambiguate XPaths for children of
BODY
withid
,class
, orrole
attributes. (1797) - Eliminate varying URL Metrics by logged-in state and discontinue disabling optimization by default for admins. (1788)
- Improve test coverage for Optimization Detective. (1817)
- Introduce
OD_Tag_Visitor_Context::track_tag()
method as alternative for returningtrue
in tag visitor callback. (1821) - Omit element node index in XPaths up to children of BODY. (1790)
- Skip visiting tags in the Admin Bar when optimizing a page. (1816)
Bug Fixes
- Ensure optimization is performed in the wp-env local environment and log debug messages to console when disabled. (1822)
- Skip visiting any tags inside of
NOSCRIPT
elements. (1783)
Documentation
0.9.0
Enhancements
- Add
fetchpriority=high
toIMG
when it is the LCP element on desktop and mobile with other viewport groups empty. (1723) - Improve debugging stored URL Metrics in Optimization Detective. (1656)
- Incorporate page state into ETag computation. (1722)
- Mark existing URL Metrics as stale when a new tag visitor is registered. (1705)
- Set development mode to ‘plugin’ in the dev environment and allow pages to be optimized when admin is logged-in (when in plugin dev mode). (1700)
- Add
get_xpath_elements_map()
helper methods toOD_URL_Metric_Group_Collection
andOD_URL_Metric_Group
, and addget_all_element_max_intersection_ratios
/get_element_max_intersection_ratio
methods toOD_URL_Metric_Group
. (1654) - Add
get_breadcrumbs()
method toOD_HTML_Tag_Processor
. (1707) - Add
get_sample_size()
andget_freshness_ttl()
methods toOD_URL_Metric_Group
. (1697) - Expose
onTTFB
,onFCP
,onLCP
,onINP
, andonCLS
from web-vitals.js to extension JS modules via args theirinitialize
functions. (1697)
Bug Fixes
- Prevent submitting URL Metric if viewport size changed. (1712)
- Fix construction of XPath expressions for implicitly closed paragraphs. (1707)
0.8.0
Enhancements
- Serve unminified scripts when
SCRIPT_DEBUG
is enabled. (1643) - Bump web-vitals from 4.2.3 to 4.2.4. (1628)
Bug Fixes
- Eliminate the detection time window which prevented URL Metrics from being gathered when page caching is present. (1640)
- Revise the use of nonces in requests to store a URL Metric and block cross-origin requests. (1637)
- Send post ID of queried object or first post in loop in URL Metric storage request to schedule page cache validation. (1641)
- Fix phpstan errors. (1627)
0.7.0
Enhancements
- Send gathered URL Metric data when the page is hidden/unloaded as opposed to once the page has loaded; this enables the ability to track layout shifts and INP scores over the life of the page. (1373)
- Introduce client-side extensions in the form of script modules which are loaded when the detection logic runs. (1373)
- Add an
od_init
action for extensions to load their code. (1373) - Introduce
OD_Element
class and improve PHP API. (1585) - Add group collection helper methods to get the first/last groups. (1602)
Bug Fixes
- Fix Optimization Detective compatibility with WooCommerce when Coming Soon page is served. (1565)
- Fix storage of URL Metric when plain non-pretty permalinks are enabled. (1574)
0.6.0
Enhancements
- Allow URL Metric schema to be extended. (1492)
- Clarify docs around a tag visitor’s boolean return value. (1479)
- Include UUID with each URL Metric. (1489)
- Introduce get_cursor_move_count() to use instead of get_seek_count() and get_next_token_count(). (1478)
Bug Fixes
- Add missing global documentation for
delete_all_posts()
. (1522) - Introduce viewport aspect ratio validation for URL Metrics. (1494)
0.5.0
Enhancements
- Bump web-vitals from 4.2.1 to 4.2.2. (1386)
Bug Fixes
- Disable Optimization Detective by default on the embed template. (1472)
- Ensure only HTML documents are processed by Optimization Detective. (1442)
- Ensure the entire template is passed to the output buffer callback for Optimization Detective to process. (1317)
- Implement full support for intersectionRect/boundingClientRect, fix viewportRect typing, and harden JSON schema. (1411)
0.4.1
Enhancements
Bug Fixes
- Fix logic for seeking during optimization loop to prevent emitting seek() notices. (1376)
0.4.0
Enhancements
- Avoid passing positional parameters in Optimization Detective. (1338)
- Send preload links via HTTP Link headers in addition to LINK tags. (1323)
0.3.1
Enhancements
- Log URL Metrics group collection to console when debugging is enabled (
WP_DEBUG
is true). (1295)
Bug Fixes
- Include non-intersecting elements in URL Metrics to fix lazy-load optimization. (1293)
0.3.0
- The image optimization features have been split out into a new dependent plugin called Image Prioritizer, which also now optimizes image lazy-loading. (1088)
0.2.0
Enhancements
- Add optimization_detective_disabled query var to disable behavior. (1193)
- Facilitate embedding Optimization Detective in other plugins/themes. (1185)
- Use PHP 7.2 features in Optimization Detective. (1162)
- Improve overall code quality with stricter static analysis checks. (775)
- Bump minimum PHP requirement to 7.2. (1130)
Bug Fixes
- Avoid _doing_it_wrong() for Server-Timing in Optimization Detective when output buffering is not enabled. (1194)
- Ensure only HTML responses are optimized. (1189)
- Fix XPath indices to be 1-based instead of 0-based. (1191)
0.1.1
- Use plugin slug for generator tag. (1103)
- Prevent detection script injection from breaking import maps in classic themes. (1084)
0.1.0
- Initial release.