An SDK (software development kit) packages one capability together with everything needed to use it: one or more APIs, runtime dependencies, configuration and credentials, documentation and samples, sometimes a command-line tool. What makes a package an SDK is not how much code it contains, but whether it hands you the surrounding work — auth, errors, tooling — along with the code.
The difference is concrete in practice. A library solves "you were tired of writing this logic, use mine". An SDK solves "you need to integrate this external capability, and I have thought through everything from authentication to failure handling".
Telling the four words apart
| Dimension |
API |
Library |
Framework |
SDK |
| Who calls whom |
You send requests |
You call it |
It calls you |
You call it, and it brings tooling |
| Shape |
An interface contract (HTTP or a function signature) |
Reusable code |
Skeleton plus conventions and lifecycle |
Package plus docs, config and samples, possibly a CLI |
| Control |
Entirely yours |
Entirely yours |
The framework decides the flow |
Yours — an SDK does not take over your app structure |
| Typical example |
REST endpoints, GraphQL |
Date handling, charting |
Front-end or back-end framework |
Cloud service SDK, payment SDK, feedback SDK |
| What you still do |
Everything |
Assemble and call |
Fill in business logic within the conventions |
Request credentials, initialise per the docs |
A one-line memory aid: an API is a contract, a library is a part, a framework is a skeleton, and an SDK is the part plus the manual plus the wiring diagram.
What is usually inside an SDK
| Component |
Purpose |
What breaks without it |
| API wrapper |
Turns HTTP details, retries and error codes into functions |
Every integrator writes it again, with different behaviour |
| Runtime and dependencies |
Makes it run in the target environment (browser, Node server) |
Version conflicts, runaway bundle size |
| Configuration and credentials |
Keys, region, environment, switches |
Hard-coded secrets, test and production mixed together |
| Docs and samples |
Gets someone to a first working call in ten minutes |
Integration depends on asking a human, and the support cost lands on you |
| Tooling (optional) |
CLI, debug panel, type definitions |
Troubleshooting becomes guesswork |
That last row is often treated as a bonus. In reality it decides the SDK's reputation: SDKs with complete type definitions and debugging tools see noticeably less rework from integrators.
Three ways to distribute, three sets of costs
| Method |
How the version is fixed |
Who upgrades |
Main cost |
| Package manager (npm and similar) |
Lockfile pins a version |
The integrator, on purpose |
Requires a build pipeline; old versions live for years |
| Script tag (CDN) |
Determined by the URL or config |
The provider |
CSP must allow the domain; caching needs designing |
| Built into a platform |
Follows the platform version |
The platform |
You control almost none of the cadence |
The script tag suits anything "visitors must also use": no install, no build, paste one line and it works. The price is that you own version compatibility and the CSP allowlist. That is why many feedback and support SDKs choose it.
The hidden cost of shipping your own SDK
Packaging a feature as an SDK is easy. Living with it for five years is not:
Backward compatibility: function names, parameters and callback timing cannot change freely once released. One change and every integrator has to follow.
Size and performance: the SDK runs on someone else's page. An extra 100KB can move their first-paint metrics.
Privacy and compliance: what you collect, how long you keep it and whether it can be turned off must be written down and actually true — our boundaries live in the privacy policy.
Observability: when the SDK itself breaks, integrators only say "your thing is broken". You need your own error reporting and version distribution.
Docs and samples: an SDK without documentation is not an SDK; the cost comes back as support tickets.
Of these five, the first three are the classic "invisible before launch, unavoidable after".
What a feedback SDK looks like
BugCapturer's Web SDK takes two steps: create a project and set a domain allowlist in the console, then put the script on the page.
html
<script>window.BugCapturerConfig={key:"bcpk_xxxxxxxx",position:"bottom-right",requireContact:false}</script>
<script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>
The configuration surface is small, and each option has a clear boundary:
| Option |
Purpose |
Watch out for |
key |
Project identifier |
Public by design; access is limited by the domain allowlist |
position |
Where the floating entry sits |
Do not cover checkout or support buttons |
requireContact |
Whether visitors must leave contact details |
Turn it off on public sites or submission rate drops |
reporter |
Reporter identity, passed in by the site |
Never hard-code one person; fill it from the session |
The visitor experience is worth stating precisely: visitors who have the extension hand capture to it, with no permission prompt at all; visitors without it get one browser permission prompt per report before the screenshot is taken. That is the browser security model, not laziness — any web SDK claiming "completely invisible screenshots" deserves a follow-up question about how it does that.
The full setup is in the Web SDK quick start; this article does not repeat it.
An SDK is not a browser extension
The two are often called "integration options", but their boundaries differ:
| Dimension |
SDK |
Browser extension |
| Who installs it |
The site, in code |
Each user, individually |
| Who it reaches |
Every visitor |
Only people who installed it |
| Source of permission |
Domain allowlist plus per-report consent |
Permissions declared by the extension |
| Best fit |
Collecting feedback from customers |
Internal testing and walkthroughs |
| Main limit |
Requires code changes on the site |
Customers will not install an extension for one site |
So "let customers report" is essentially an SDK-or-share-link problem; an extension is for internal use. The trade-off is covered in Chrome Extension vs Desktop Tools.
Reading an SDK's version numbers
Versioning matters more than for a normal library, because the person upgrading is not you:
- Major: incompatible changes; integrators must edit code.
- Minor: new features, backward compatible; usually safe.
- Patch: bug fixes; lowest risk.
With script-tag distribution, the version lives in the URL. Providers should offer two modes: pinned (the integrator decides when to move) and auto-update (always latest). Pinned is stable; auto is convenient, but only if you are confident an update will not break someone's page — which is exactly where many SDK incidents come from.
Five questions before you integrate any SDK
| Question |
Why it matters |
What a good answer looks like |
| What permissions does it want? |
Scripts and extensions can read page content |
Minimal scope, each item explained, can be disabled |
| What data does it collect? |
Compliance and customer trust |
A clear list, sensitive fields masked, a retention period |
| Will a failure take the page down? |
Third-party script errors can cascade |
Timeouts do not block the main flow; errors are isolated |
| Size and load timing? |
Direct impact on first-paint metrics |
Async loading, lazy init, a published size |
| How do we leave? |
Migration cost is usually underestimated |
Data export, one-line removal, no leftovers |
Questions two and five are the ones people skip, and the ones that become a problem six months later.
Build it or buy it
| Your situation |
Recommendation |
| The capability is your core business (you are the payment company) |
Build it; the SDK is the product |
| You just need an entry point and have nobody to maintain it |
Buy or adopt one, and spend the engineering time on the business |
| Compliance requires data to stay inside your network |
Build or self-host, after pricing the maintenance |
| Fewer than five engineers and no front-end infrastructure |
Start with a script tag; do not build a packaging system |
The only test that matters: will this capability keep eating your engineering roadmap? If yes, build it. If not, do not take on a long-term liability for the feeling of control.
Three common misconceptions
- Calling an API an SDK: a set of endpoint docs with no wrapper, no samples and no configuration is an API.
- Treating an SDK as a framework: an SDK should not take over your app structure. If it dictates your folder layout, it is a framework.
- Bigger is better: an SDK that does everything usually means a large bundle, broad permissions and risky upgrades. Import what you need.
FAQ
What is the relationship between an SDK and an API?
An SDK usually contains a wrapper around an API. The API is the contract; the SDK is an implementation of that contract with tooling and docs.
SDK versus library in one sentence?
A library is code you call. An SDK is everything you need to integrate one capability — including the library, configuration, docs and tools.
Is a front-end script tag an SDK?
Yes. Distribution does not decide whether it is an SDK; it only decides how versions and upgrade responsibility are split.
Does an SDK affect page performance?
Yes, depending on size and load timing. Loading asynchronously and initialising on demand is the normal pattern; the provider should publish its size.
Do I need to change my build setup to integrate one?
Not for a script tag — that is why it suits public sites. A package manager does require it, in exchange for version pinning and type hints.