Optimization Detective

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

  1. Visit Plugins > Add New in the WordPress Admin.
  2. Search for Optimization Detective.
  3. Install and activate the Optimization Detective plugin.

Manual installation

  1. 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.
  2. Visit Plugins > Add New Plugin in the WordPress Admin.
  3. Click Upload Plugin
  4. Select the optimization-detective.zip file on your system from step 1 and click Install Now.
  5. 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-beta2

Enhancements

  • Account for 64 KiB limit for sending beacon data. (1851)
  • Add post ID for the od_url_metrics post to the tag visitor context. (1847)
  • Change minimum viewport width to be exclusive whereas the maximum width remains inclusive. (1839)
  • Disable URL Metric storage locking by default for administrators. (1835)
  • Include active plugins in ETag data and increase default freshness TTL from 1 day to 1 week. (1854)
  • Make ETag a required property of the URL Metric. (1824)
  • Use CSS range syntax in media queries. (1833)
  • Use IFRAME to display HTML responses for REST API storage request failures in Site Health test. (1849)

Bug Fixes

  • Prevent URL in Link header from including invalid characters. (1802)
  • Prevent optimizing post previews by default. (1848)

Documentation

  • Improve Optimization Detective documentation. (1782)

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 with id, class, or role 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 returning true 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 to IMG 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 to OD_URL_Metric_Group_Collection and OD_URL_Metric_Group, and add get_all_element_max_intersection_ratios/get_element_max_intersection_ratio methods to OD_URL_Metric_Group. (1654)
  • Add get_breadcrumbs() method to OD_HTML_Tag_Processor. (1707)
  • Add get_sample_size() and get_freshness_ttl() methods to OD_URL_Metric_Group. (1697)
  • Expose onTTFB, onFCP, onLCP, onINP, and onCLS from web-vitals.js to extension JS modules via args their initialize 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.