š This document provides technical details of installing the Botify JavaScript snippet in your website pages. Refer to the PageWorkers Implementation article for basic installation instructions.
Overview
Like any script added to a webpage, the Botify JavaScript snippet is a resource, and if improperly loaded, it can impact the browserās HTML parsing and rendering process. This guide includes recommendations on installing the Botify JS snippet on your page, including which behaviors to avoid, to get the full benefit of Botify optimizations with minimal impact on your pages' perceived load speed.
About the Snippet Installation Method
We recommend you install the Botify JS snippet manually in your source code. While you can install it with a third-party tag manager (e.g., Google Tag Manager), we donāt recommend this because a tag manager:
Drastically reduces the flexibility in tag insertion.
Will generally safeguard the loading of your page over the speed of executing the script.
Introduces many advanced configurations that may interfere with loading the Botify snippet (e.g., scripts not loaded because of cookie banners or consent manager platform settings and scripts not loaded for bots).
Inserting the Snippet in your HTML Document
The following methods of installing the Botify snippet minimize the impact on these DOM events: DOMContentLoaded (DCL), FirstPaint (FP), FirstContentfulPaint (FCP), LargestContentfulPaint (LCP), and OnLoad (L).
Because the Botify snippet code is asynchronous (i.e., the snippet executes code in chunks, waiting for several external cues before executing the code), its execution time following download will not occupy the browserās main thread for an extended time. Therefore, it will not risk delaying DOMContentLoaded by a significant margin. The duration of the snippetās main execution that could occur before firing DOMContentLoaded is less than 50ms.
We recommend three installation configuration options depending on your website architecture (e.g., Multiple-Page Application vs. Single-Page Application) and current browser performance:
š” Always load the Botify JS snippet via a script that contains the async attribute to guarantee the snippetās loading time will not negatively impact DOMContentLoaded.
Speed-Focused Configuration
This option maximizes the Botify JS snippet execution speed. Since Botify optimizations perform changes on your website that you want users and bots to see as fast as possible, these changes should be applied quickly once your page is loaded. The best way to ensure a rapid download and execution of the Botify snippet is to load it in your documentās head.
We recommend this configuration if any of the following are true:
Your website is a Multiple-Page Application (MPA), where a new HTML page loads on each navigation, vs. a Single-Page Application (SPA), where JavaScript renders new HTML on navigation.
Your website's main content (excluding assets, stylesheets, and images) is not heavily dependent on JavaScript resource loading and execution.
Your websiteās main content (excluding assets, stylesheets, and images) loads rapidly.
Content-Focused Configuration
This option executes the Botify JS snippet after other resources. If your website loads many resources critical for your page to load and you are unsatisfied with your page load speeds, you may append the Botify snippet to the HTML documentās body instead of the head. In this configuration, the browser will not prioritize loading the snippet over other resources loaded through the head.
We recommend this configuration if any of the following are true:
Your websiteās main content (excluding assets, stylesheets, and images) is heavily dependent on JavaScript resource loading and execution.
Your websiteās main content (excluding assets, stylesheets, and images) loads slowly.
š Because browsers anticipate resources that will be requested by the document at a later stage, this technique may show similar loading performance results as when the Botify JS snippet is in the documentās head. Unlike loading the script in the head, the script will only be executed after the HTML parsing has reached the script location on the page.
SPA and SSR Frameworks Configuration
This configuration relies on framework tools to dynamically inject the Botify JS snippet on the client side in your documentās body. SPA and Server-side Rendering (SSR) frameworks rely heavily on JavaScript hydration to display content on the page. These frameworks load an initial HTML page and the critical JavaScript resources are loaded immediately after. The display of the main content depends on the execution of these critical resources.
If Botify optimizations are loaded and executed before or at the same time as critical resources, optimizations may be attempted before the relevant content is displayed on the page. Although the Botify snippet is designed to handle this by reapplying them as many times as possible, it is preferable to avoid this and only execute the snippet when the page is ready to be modified.
For this purpose, SPA/SSR frameworks favor inserting external scripts dynamically on the client side and appending them to the documentās body. This preserves the main DOM events from being impacted by the inserted scripts and allows time for their content to be displayed before executing the external scripts.
āļø The Botify JS snippet can be implemented on websites that use these frameworks.
Refer to the framework-specific guides to obtain the desired result for the most popular front-end frameworks, as each may have its own method of implementing this behavior.
Visit the following pages for detailed tutorials on inserting the Botify JS snippet on these frameworks:
Comparing SSR SPAs and Non-SSR SPAs
Unlike traditional SPAs that rely on JavaScript executed on the client side to render the HTML entirely (i.e., SPAs that do not support SSR), SSR-enabled SPAs are rigidly structured into predefined pages that can be precompiled on the server side and delivered as HTML documents to be loaded in the browser without any JavaScript execution.
Two main advantages are:
The initial load time of the landing page is much faster.
JavaScript execution is unnecessary to render a page without interaction, which is useful for bots since they may not always execute JavaScript.
When navigating an SSR-enabled SPA in the browser, the browser will not load a new HTML document on each navigation, just as it does in a regular SPA. Instead, the SSR-enabled SPA handles the navigation using JavaScript (if JavaScript execution is allowed in the context) and preloaded page metadata. Additional JavaScript files may be loaded as needed; however, the original HTML document remains unchanged.
This causes the first important consequences for Botify optimizations:
š Whether a SPA uses SSR or not, the Botify JS snippet will only be executed when landing on a page on the client side and will not be:
Re-executed on further website navigation.
Executed on the server side.
Configurations to Avoid
We have measured in extreme cases, immediate execution scripts and defer scripts may cause significant delays to the firing of DOM events such as DOMContentLoaded. Since your browser relies on these DOM events to render the page during parsing, we recommend never using either of the following configurations:
Script tag with the
deferproperty.Script tag with immediate execution (lacking
deferorasync).
š When the script loading the tag is appended dynamically to your page on the client side (e.g., by a front-end framework), it may be acceptable to load it without the async attribute since its insertion is guaranteed to be performed after your DOMContentLoaded has been fired.
However, dynamic insertion will negatively impact the Botify JS snippet load speed since it will load later than your other resources. This method is more commonly used on SPAs, which rely heavily on JavaScript sources being loaded and executed first.
Snippet Installation
There are two main considerations to address when incorporating the Botify snippet in your applicationās source code:
Snippet Scope: Global vs. Local
You can either install the Botify snippet at the top level of your application so it will be applied to all its pages, or add it to a specific subset of its pages.
š We recommend adding the snippet globally at the top level of your application so it is always loaded and executed on all pages.
Snippet Loading Priority
As outlined above, you can load the snippet with different priorities in your webpage. In the framework-specific articles, we respect the recommendations established here, constrained by each framework's possibilities.
š We recommend dynamically loading the Botify JS snippet in the HTML documentās body with SSR frameworks that rely heavily on JS hydration to display page content. This will only load Botify optimizations once it has rendered the main components of the page, which avoids conflicts between JS hydration and Botify optimizations.
See also: