Understanding the Smart Preloader

This article contains information about the Smart Preloader, how it works, and how you can use it to improve the user experience for your customers, and make sure they don't leave your website in the case when your origin needs just a little bit more time to respond.


What is the Smart Preloader?

The Smart Preloader is a system that monitors dynamic HTML requests going through bunny.net. If the system detects a request is slow, and might be negatively impacting the user experience, it will respond to the user with a special preloader screen HTML response.

This will present the user with a better experience while presenting them with your branding and loading animation while letting them know that the website is still loading.

After this, the loading screen will immediately reconnect to the original request sent back to the origin.

  Cookie Notice

To ensure great performance without impacting the original request, the Smart Preloader service might set cookies to the preloader HTML responses. We use this to identify the reload request from the preloader screen and tie it back to the original request without causing issues.

At bunny.net, we take privacy very seriously. The cookies are never used for any purpose outside of this requirement, and are not used for tracking, monitoring, or any other metrics of the end user.


When can the Smart Preloader trigger?

To ensure seamless integration, the Smart Preloader screen will only trigger during specific requests. This section defines these conditions we use to determine when the smart preloader should be shown.

The Smart Preloader will trigger if the following conditions are met:

  • The request method is GET
  • The request URL has either no extension or has one of the following extensions: .html, .htm
  • The request is not triggered by a web crawler or bot
  • The request does not contain the X-Requested-With header
  • The request path does not start with /api/
  • The request path does not start with /ajax/
  • The request path does not start with /wp-admin/

During the Preview period, we will be carefully evaluating the conditions to ensure maximum compatibility and as little false positive triggers are happening. If you run into any issues with the Smart Preloader affecting your requests that should not trigger the preloader screen, please get in touch with our Super Bunnies support team, and we will be happy to assist.


Understanding the Trigger Delay

The main concept of the Smart Preloader is that this is only shown in cases where the origin is taking longer to reply than intended. To control that, we added a setting called Trigger Delay. This helps you configure the time limit within which bunny.net will expect the origin to respond. Once the time limit passes, the Smart Preloader system activates and shows the loading screen to your user. 

For example, if your website usually responds within 700 milliseconds, and the trigger delay is set to 700 milliseconds, this will mean most users never see the preloading screen.

It's only when your origin takes longer than that, for example, 2 or even 5 seconds to respond, the system will kick into action and ensure to your users that something is going on and that the website is on the way.


Configuring a custom preloader HTML

The preloader screen can be configured to display a custom HTML that is completely customizable by you. Under the hood, the preloader screen will contain a tiny snippet of code that almost immediately refreshes the page. During this time, the request is immediately reconnected to the original request that was waiting for the origin to respond.

To ensure that this snippet is included, your code should include the tag {{preloader_script}} within the body of the source code.

📘 HTML Validity Notice

To make sure that the preloading script is working correctly, make sure that the configured HTML contains no JavaScript or HTML errors that could prevent the website from executing the injected script. To connect with the original request, the preloading screen will trigger a page refresh using the injected code, which is crucial to make sure that the request does not get stuck in the system. 


What happens if the origin never responds?

The Smart Preloader connects and intercepts with the standard request lifetime logic within bunny.net. If your origin does not respond at all, a standard 504/502 error will be returned, letting your users know that there has been an issue.

Furthermore, all the existing feature sets, including Perma-Cache, SafeHop, and Origin Shield, will continue to operate as normal with the Smart Preloader enabled.


Why does the browser return a 529 status code to the end user?

The Smart Preloader screen returns to the end user as valid HTML responses. As this is a temporary request that the browser should not cache or process, we return a 529 status code to the end user while showing the preloader.

Table of Contents

Was this article helpful?
3 out of 3 found this helpful