SDK Installation

Add ConsentStack to your website with a single script tag. Supports all frameworks and static sites.

The ConsentStack SDK is a single JavaScript file 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 script tag

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

<script
  src="https://cdn.consentstack.io/consent.js"
  data-site-key="YOUR_SITE_KEY"
  defer
></script>

The defer attribute tells the browser to download the script in parallel and execute it after the HTML is parsed. This means the SDK never blocks your page render.

You can also use async instead of defer. The difference: async executes the script as soon as it downloads (potentially before the DOM is ready), while defer waits until parsing is complete. Both load without blocking -- defer is the recommended default because it guarantees the DOM is available when the SDK initializes.

Place the ConsentStack script tag before any third-party scripts in your <head>. The SDK installs a script observer at parse time — scripts that appear after ConsentStack in the HTML are caught and blocked before they execute. Scripts that appear before it may execute 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.v0.1.0.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 current version is 0.1.0, and the SDK weighs approximately 21 KB (gzipped). It loads asynchronously and has zero dependencies.

Data attributes

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

Attribute	Required	Default	Description
`data-site-key`	Yes	--	Your site's public key from the dashboard (e.g. `csk_abc123def456`). Identifies which consent configuration to load.
`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

<script
  src="https://cdn.consentstack.io/consent.js"
  data-site-key="csk_abc123def456"
  data-mode="banner"
  data-debug="true"
  data-debug-panel="true"
  defer
></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 script tag to your root layout so it loads 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 */}
        <script
          src="https://cdn.consentstack.io/consent.js"
          data-site-key="YOUR_SITE_KEY"
          defer
        />
        {/* 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 -->
    <script
      src="https://cdn.consentstack.io/consent.js"
      data-site-key="YOUR_SITE_KEY"
      defer
    ></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 script tag to your site's <head>.

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

Verifying your installation

After adding the script tag, 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 see detailed logs for config loading, region detection, and script blocking activity.

If the banner does not appear, verify that your data-site-key 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