Async Problem
Sessions not recording after adding the async attribute to the Zipy script tag.
Zipy SDK Not Initialising When Using async Script Loading
The Problem
The standard Zipy installation uses two script tags in your HTML — one to download the SDK and one to call zipy.init(). This works correctly when both scripts load in order:
However, if you add the async attribute to the first script tag, the browser downloads the SDK in the background without blocking the rest of the page. This means the second script — the one calling zipy.init() — can execute before the SDK has finished loading, causing the initialisation to fail silently.
⚠️ Why This Happens
The async attribute tells the browser to download the script in parallel without blocking page rendering — but it also means execution order is no longer guaranteed. Because the two scripts are separate tags, there is no contract that the SDK will be ready by the time zipy.init() is called. The result: window.zipy is undefined at the time of init, the SDK never initialises, and no sessions are recorded.
Symptoms you may notice:
No sessions being recorded in Zipy.
No errors visible in the Zipy dashboard despite errors occurring in your app.
Sessions start recording intermittently (race condition — SDK sometimes loads first, sometimes not).
No console errors indicating a failure, because the window.zipy && guard silently skips the init call when the SDK is not yet available.
Solutions
There are two ways to fix this. Choose the one that best fits your setup.
Solution 1 — Remove the async Attribute (Recommended)
The simplest fix is to remove the async attribute from the Zipy script tag. This restores normal script execution order and ensures zipy.init() is called only after the SDK has fully loaded.
❌
Before
<script async src="https://cdn.zipy.ai/sdk/v1.0/zipy.min.umd.js"
crossorigin="anonymous"></script>
<script>
window.zipy && window.zipy.init('YOUR_PROJECT_SDK_KEY');
</script>
✅
After
<script src="https://cdn.zipy.ai/sdk/v1.0/zipy.min.umd.js"
crossorigin="anonymous"></script>
<script>
window.zipy && window.zipy.init('YOUR_PROJECT_SDK_KEY');
</script>
✅ Result
The SDK is guaranteed to be fully loaded before zipy.init() runs. Sessions will be recorded normally. This is the recommended approach for most setups.
Solution 2 — Keep async, Use the onload Callback
If you need to keep async script loading — for example, because your site enforces performance policies or uses a tag manager that injects scripts asynchronously — you can use the script onload callback pattern. This guarantees that zipy.init() is only called after the SDK has finished loading, regardless of network timing.
Solution 2 — async with onload callback
<script>
// Create the script element
var script = document.createElement("script");
script.src = "https://cdn.zipy.ai/sdk/v1.0/zipy.min.umd.js";
script.async = true;
// Ensure zipy.init() runs only after the SDK has fully loaded
script.onload = function () {
if (window.zipy) {
window.zipy.init("<YOUR_PROJECT_SDK_KEY>");
}
};
// Append the script to the document head
document.head.appendChild(script);
</script>
💡 How This Works
Instead of relying on two separate script tags, this approach programmatically creates the script element and attaches an onload handler. The onload function fires only after the browser has completely downloaded and executed the SDK — at which point window.zipy is guaranteed to be available. zipy.init() is then called safely inside this callback.
✅ Result
The SDK loads asynchronously without blocking the page, while zipy.init() is guaranteed to execute only after the SDK is ready. Use this approach if you cannot remove async from your script loading strategy.
Last updated