WordPress Theme Bug Fix for LiteSpeed Cache Analytics Referrer

Some WordPress theme have a bug that the referrer does not get passed to Analytics tools like GA4 and Jetpack Stats when the LiteSpeed Cache plugin is configured to Guest Mode. Broken analytics is frustrating. Not knowing the source of traffic is like being blind. It’s difficult to know if your marketing efforts are performing how you expect. Read below for a solution to get the source/medium to report correctly from the document referrer.

WordPress Theme breaks LiteSpeed Cache from passing the document referrer to analytics platforms

LiteSpeed Guest Mode

Guest Mode is a feature of LiteSpeed to help the page load quicker. First a copy of the page is fetched from the cache – loading as fast as possible. This ensures the browser can build the page as quick as it can, though the content may not be 100% accurate based on the language, region, etc.

Next the browser quickly makes an AJAX call to fetch the accurate information for the page and re-write the content. The net result is a quick loading page that garners very high Google PageSpeed Insights ratings.

Here you can see the Javascript redirect occurred in the browser.

Javascript redirect occurring from LiteSpeed Guest Mode

The Flaw with LiteSpeed Guest Mode and Referrer

Guest Mode can cause a flaw in terms of analytics tools. Let’s say the visitor came from a search engine – the browser knows this is the referrer. However before the browser has a chance to report the hit to analytics tools the page refreshed from the AJAX call – a call to itself. Once the page is fully loaded the second time, the referrer now looks like it came from itself. The net result is that the analytics tools see the referrer as direct.

The LiteSpeed Cache WordPress plugin has a solution for this by adding a block of Javascript at the top of the page that catches the original referrer, stores it in sessionStorage (temporary storage location within the browser) temporarily. It then uses this to set the document referrer after the second page load.

Why Themes Don’t Set the Referrer Correctly

I’ll be fully honest here… I don’t have the answer as to why some themes don’t work correctly with the solution that the LiteSpeed Cache WordPress plugin has provided. When I’ve seen this happen, this is what occurs.

The code execution gets into the finalize() function in file litespeed-cache/src/gui.cls.php and it gets to this check:

The 2nd and 3rd conditions return false and as a result the needed Javascript snippet isn’t added to the of the page.

A Fix for WordPress Themes that Don’t Report the Referrer to Analytics

I came up with this patch in a child-theme functions.php file that fixed the document referrer not being correctly set in analytics tools issues. Now this solution doesn’t put the LiteSpeed Javascript as close to the opening <head> tag as the LiteSpeed Cache plugin does, but since it is added before WordPress stats and Google Analytics 4 scripts are added it works as needed.

Before and After Graphs

After implementing the above patch we can see the analytics charts are correcting themselves. JetPack Stats doesn’t show a time-based graph and I didn’t capture before screenshots of the traffic counts by Referrer.

Google Analytics 4

GA4 analytics graph of source medium before and after the LiteSpeed document referrer outage
GA4 Source/Medium became inaccurate when the site was switched to a theme that is not compatible with LiteSpeed Cache. Once the code patch was applied the graph right-sided itself.

References