SDK Installation

Add ConsentStack to your website with three tags (a preconnect hint plus stub plus core). Supports all frameworks and static sites.

The ConsentStack SDK ships as three tags (a preconnect hint plus stub plus core) that you add to your site's <head>. It handles consent collection, script blocking, geo-detection, and banner rendering, no build step required.

This page covers every installation option. If you just want to get running fast, start with the Quickstart and come back here when you need more control.

The install tags

Add these three tags to your site's <head>, replacing <YOUR_SITE_KEY> with the key from your dashboard:

<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>

The preconnect link warms the TLS connection to the CDN while the browser parses the script tags. It is optional but recommended for fastest first paint.

Do not add defer or async to either ConsentStack script tag. The SDK must execute synchronously before other scripts in the page. It installs a script observer at parse time that intercepts third-party scripts before they run. With defer or async, other scripts can execute before the observer is active, bypassing consent enforcement entirely.

Place both ConsentStack script tags as the first scripts in your <head>, with the stub before the core. Scripts that appear after ConsentStack are caught and blocked before they execute. Scripts that appear before it may run before the observer is active.

CDN and versioning

The SDK is served from cdn.consentstack.io, a global CDN backed by Cloudflare R2.

Two URL patterns are available:

https://cdn.consentstack.io/consent.js                   (latest, 5 min cache)
https://cdn.consentstack.io/consent-body-v0.3.6.js       (versioned, immutable)

The latest URL always serves the most recent release. The versioned URL is immutable and cached for one year. Use it to pin a specific version. The canonical immutable URL pattern is consent-body-v{version}.js.

The current version is 0.3.6, and the SDK ships as two scripts totaling roughly 30 KB gzipped (stub 7 KB plus core 23 KB), plus a preconnect link tag for the CDN. It executes synchronously at parse time so it can intercept tracker requests before they fire, and has zero dependencies.

Data attributes

Configure the SDK's behavior using data- attributes on the core script tag. No JavaScript configuration file needed.

Attribute	Required	Default	Description
`data-site-key`	No (legacy fallback)	(none)	The site key is read from the `?k=` URL param on both script tags. `data-site-key` is a legacy attribute used only by single-file React loader builds.
`data-mode`	No	`"banner"`	Set to `"headless"` to run consent logic without rendering any UI. Useful when you want to build a custom consent interface. Learn more about headless mode.
`data-debug`	No	`false`	Set to `"true"` for verbose console logging. Logs config loading, consent decisions, script blocking, and API calls.
`data-debug-panel`	No	`false`	Set to `"true"` to load a visual debug overlay on the page. The panel is loaded automatically from CDN. Displays real-time consent state, blocked scripts, and detected region.

Example with all options

<link rel="preconnect" href="https://cdn.consentstack.io" />
<script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
<script
  src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"
  data-mode="banner"
  data-debug="true"
  data-debug-panel="true"
></script>

Only enable data-debug and data-debug-panel during development. Both add console output and UI overlays that your visitors should not see.

Hash trigger for preferences

The SDK listens for the URL hash #cs-preferences. When a visitor navigates to any page with this hash, the preferences panel opens automatically.

This is useful for "Manage cookies" or "Privacy settings" links in your site footer:

<a href="#cs-preferences">Manage cookie preferences</a>

The hash works from any page where the SDK is loaded. It also works as a direct link. If someone visits https://yoursite.com/#cs-preferences, the preferences panel opens on page load. The SDK cleans the hash from the URL after opening the panel, so it does not persist in the address bar.

Framework examples

Next.js (App Router)

Add the tags to your root layout so they load on every page:

app/layout.tsx

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        {/* ConsentStack must appear before third-party scripts */}
        <link rel="preconnect" href="https://cdn.consentstack.io" />
        <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>" />
        <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>" />
        {/* Third-party scripts go after ConsentStack */}
      </head>
      <body>{children}</body>
    </html>
  );
}

Plain HTML

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Website</title>
    <!-- ConsentStack must appear before third-party scripts -->
    <link rel="preconnect" href="https://cdn.consentstack.io" />
    <script src="https://cdn.consentstack.io/consent.js?k=<YOUR_SITE_KEY>"></script>
    <script src="https://cdn.consentstack.io/consent-core.js?k=<YOUR_SITE_KEY>"></script>
    <!-- Third-party scripts go after ConsentStack -->
  </head>
  <body>
    <h1>Hello world</h1>
  </body>
</html>

Other frameworks

The SDK works with any framework or static site generator (Astro, Gatsby, Nuxt, SvelteKit, WordPress, Shopify, and more). The pattern is always the same: add the preconnect link and both script tags to your site's <head>.

For framework-specific details and edge cases, see Framework Guides.

Verifying your installation

After adding the install tags, open your site in a browser and check:

Look for the banner. A consent banner should appear based on your published configuration.
Check the console. Open your browser's developer tools and look for [ConsentStack] log messages. If you see an initialization success message, you are connected.
Enable debug mode. Add data-debug="true" to the core script tag to see detailed logs for config loading, region detection, and script blocking activity.

If the banner does not appear, verify that the ?k= site key on both script tags matches the key shown in your dashboard and that you have published a consent configuration for your site.

What's next

JavaScript API. Programmatic access to consent state via window.consentstack.
Headless Mode. Run consent logic without the built-in banner UI.
Framework Guides. Detailed integration instructions for popular frameworks.

On this page