Implementation worksheet · 6 min read
An Onboarding SDK Performance Budget Worksheet
Commit to four numbers and publish them: gzipped bytes for the initial load, additional bytes loaded lazily, main-thread time attributable to your script, and the maximum shift in the host's Core Web Vitals caused by loading it. Measure the fourth with a controlled comparison — the same page with and without the script, repeated — rather than by reading a page score, because a page score attributes everything on the page to the page. Enforce the first three in the build so they fail rather than drift. Publishing the numbers is the part that matters: an SDK vendor who will not state a size budget is one whose size is not budgeted.
An onboarding or guidance SDK loads inside a customer's application, competing with their code and every other third-party script for the same main thread. Its cost is invisible in your own metrics and entirely visible in theirs, which means the incentive to measure it honestly has to be manufactured rather than assumed. This guide is written from the vendor side and we are one.
Put it into practice
1. Split initial from lazy, and budget them separately
What must load before the SDK can do anything, versus what loads when a tour actually runs. Combining them into one number hides the figure that matters most — the cost imposed on every page load, including the ones where nothing is shown.
2. Budget main-thread time, not only bytes
Bytes are easy to quote and an under-measure. Parse, compile and execution time is what delays interactivity, and a small heavily-computational script can cost more than a larger passive one. Measure on a mid-range device rather than a development machine.
3. Measure Core Web Vitals impact with a controlled comparison
The same page, same network conditions, repeated runs, with and without the script. Report the difference. A page score with your script present tells you about the page; the difference tells you about your script, and only the second is a claim you can defend to a customer.
4. Fail the build on the budget
Automated, in CI, with the number in version control. A budget reviewed by a human drifts upward in increments that are each individually reasonable. This is the only mechanism that holds, and adopting it is a decision to occasionally block your own release.
5. Test with other third-party scripts present
Your SDK will never be the only guest. Main-thread contention with analytics, chat and tag managers changes the picture, and a measurement taken on an otherwise empty page is optimistic in exactly the direction that flatters you.
6. Publish the numbers where customers can find them
In documentation, with the measurement method and the date. This is the uncomfortable step and it is the one that makes the budget real — a number a customer can hold you to is a number that gets defended internally when someone proposes a feature that would exceed it.
7. Re-measure every release and keep the history
A trend line of size and main-thread time across versions. Individual releases each add a little; the history is what makes the accumulation visible, and it is the artefact that prevents the slow slide nobody notices.
The performance budget
Copy this structure into your review document and record your observed result for each row.
| Metric | Budget | Measured | Method |
|---|---|---|---|
| Initial bundle, gzipped | build output | ||
| Lazy-loaded bundle, gzipped | build output | ||
| Main-thread time, mid-range device | profiled, repeated runs | ||
| LCP delta (with vs without) | controlled comparison | ||
| INP delta (with vs without) | controlled comparison | ||
| CLS delta (with vs without) | controlled comparison | ||
| Requests added on initial load | network panel | ||
| Measured alongside other third-party scripts | yes/no | ||
| Published in documentation | yes/no | ||
| Date last measured |
A failure worth checking
Quoting the page score. A vendor reports that pages running their SDK score well on Core Web Vitals, which is true and answers nothing — those pages might score better still without it, and the score is dominated by the customer's own application. The number a customer needs is the delta, and it is harder to produce and less flattering to publish. A page score presented as evidence of low impact is the specific claim to distrust, ours included.
Common questions
What is a reasonable size budget?
It depends on what the SDK does, and the useful discipline is committing to a number and publishing it rather than finding the right one first. A vendor who will not state a budget has not set one, which is the more informative fact.
Should the SDK load asynchronously?
Almost always, and that is table stakes rather than an achievement. Asynchronous loading removes the render-blocking cost and does not remove the main-thread cost, which arrives later and still delays interactivity.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.