How to Install the Captain Compliance Consent Banner on Next.js, React, and Other Single-Page Apps

Edited

This article explains how to add the Captain Compliance consent banner to a single-page app, such as a site built with Next.js or React. In these apps the browser loads one HTML document and the framework changes pages without a full reload, so the script is added once, at the root of the app.

Before you start

  • Add the site’s domain in Captain Compliance and set up its consent banner. See How to Set Up Captain Compliance: A Step-by-Step Checklist.

  • Open the Installation script section for that domain. In the Captain Compliance app, select Consent banner in the sidebar, select the domain, and under Setup select Installation script. The section has a snippet for each method below, already filled in with your access token.

The script runs only on the domain it was issued for, with or without www. On a subdomain, the banner appears only if that subdomain has been added in Captain Compliance. On any other address, the banner does not appear. For example, the banner does not appear on localhost or on a preview deployment address. Test on the domain that you added in Captain Compliance. To add a domain or subdomain, see How to Scan Websites and Manage Domains.

The Installation script section in the Captain Compliance app:

The Installation Script section of the Captain Compliance app, showing the Script Tag Method snippet with a placeholder access token

Next.js

Use the Next.js Method snippet. It loads the script with the next/script component in the root layout of an App Router project.

// app/layout.tsx
import Script from 'next/script'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://api-prod.cptn.co/banner/script?accessToken=YOUR-ACCESS-TOKEN"
          strategy="afterInteractive"
        />
      </body>
    </html>
  )
}

In a Pages Router project, add the same Script component to pages/_app.tsx.

React

Use the React Method snippet. It adds the script from the root component when the app starts.

// src/App.tsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = "https://api-prod.cptn.co/banner/script?accessToken=YOUR-ACCESS-TOKEN";
    script.setAttribute('access-token', 'YOUR-ACCESS-TOKEN');
    script.async = true;
    document.body.appendChild(script);
    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return (
    <div>
      {/* Your app content */}
    </div>
  );
}

export default App;

Keep this code in the root component, so that it runs once and not on every route change.

Other frameworks

For Vue, Angular, Svelte, and static site generators, use the Script Tag Method snippet. Paste it into the head of the HTML document that the app loads, which is usually index.html or the framework’s document template.

<script src="https://api-prod.cptn.co/banner/script?accessToken=YOUR-ACCESS-TOKEN"></script>

Notes for single-page apps

Install through Google Tag Manager instead

If the app already loads GTM, you can load the banner from GTM instead of adding the script in code. Add the Captain Compliance CMP template to the container, enter the access token for the domain, and set the tag to fire on Consent Initialization - All Pages. See How to Install and Configure the Captain Compliance CMP Template in GTM.

Use one method only. If you install through GTM, do not also paste the script into the site.

Confirm the banner is live

  1. Deploy the app, and open it on the domain that you added in Captain Compliance, in a private or incognito browser window.

  2. Confirm that the banner appears, and try Allow, Reject, and Cookie Settings.

  3. In the browser’s developer tools, open the Network tab, reload the page, and confirm that the request to api-prod.cptn.co succeeds.

  4. Move between a few pages in the app and confirm that the banner does not reappear after you choose.

If the banner does not appear, see How to Troubleshoot a Consent Banner That Does Not Appear or Respond. For a full test plan, see How to Test Consent Banner Configuration & Behavior.

Related articles