What Is an SDK? SDK vs Library vs Framework vs API

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.