There are several speed metrics out there that get a lot of attention. Largest Contentful Paint is really useful for lots of sites because it tends to match up with when a user sees the page as being more or less loaded. Similarly, First Contentful Paint is useful because it's a good indicator to the user that the page has started loading.
But while FCP and LCP are useful metrics, they're not perfect. LCP is currently only reported by Chrome, so you won't get to see that data for anyone using, for example, iOS. And for most ecommerce sites, that's a big percentage of users.
And what if there are other things that are really important to you? For an ecommerce site, you might want to track when the first product image loads on a category page, or when the heading text loads on the product page. Knowing this means you know when important content on the page starts to be shown to users.
Tracking your own metrics
Here's where the User Timing API comes in. The User Timing API uses JavaScript to set a performance mark in the browser - a highly detailed timestamp tracking when that JavaScript executed. Because of the nature of JavaScript, you can set this mark immediately after an element in the HTML, and it will give you the time it took for that element to load.
Example 1: tracking the product heading
For your product pages, if you want to know when the H1 heading for the product page was rendered, you could set a performance mark immediately after the H1 code, like this:
<h1>Nike Air Force 1</h1>
<script>performance.mark("Product Heading Rendered")</script>
Example 2: tracking when an image is rendered
You can use a similar method if you want to track when a particular image has loaded. For ecommerce sites, it can be useful to know when the first product image has loaded on a category page. For this site, we track when the main hero image appears on the homepage - and here's how you can do it too.
<img src="hero.jpg" onload="performance.clearMarks('Hero Image Loaded'); performance.mark('Hero Image Loaded');">
<script>
performance.clearMarks('Hero Image Loaded');
performance.mark('Hero Image Loaded');
</script>
This method is slightly different, and requires a bit of explanation. We're calling performance.mark twice - once on an onload attribute on the image, and once immediately after the image tag. We want to find the maximum value of those and use that, so for both methods we use performance.clearMarks to reset that mark. This results in only one performance mark - and it'll have the later (accurate) time.
Solving the cross-browser problem
There's another huge benefit to using custom timings like this: they're compatible with the vast majority of browsers.
I first discovered this from Katie Sylor-Miller, a frontend architect for Etsy. Katie's post on the Core Web Vitals also mentioned how Etsy has a custom timing that fires immediately after their SVG logo is rendered, which results in a close enough representation of FCP, and that it works across all modern browsers. It's a super clever way of getting around the browser limitation (and one that this site also does - we also have a custom timing that fires immediately after our logo renders, inspired by Etsy).
How to use Blackbird to track custom timings
Once you've set up performance marks on your site, you can tell Blackbird to start tracking them. Under "Custom Metrics", click "Track a Custom Metric", and add the name of your new performance mark. Blackbird will then start tracking real user data for your new metric automatically.