HubSpot Cookie Banner API: Run Scripts Only After Visitors Consent
Posted by

HubSpot Cookie Banner API: Run Scripts Only After Visitors Consent

If your HubSpot site loads third-party scripts such as analytics, ad pixels or chat widgets, those scripts should respect what the visitor chose in the cookie banner. HubSpot's cookie banner exposes a small JavaScript queue, _hsp, that lets your own code react to that choice. This article shows the practical pattern: wait for consent, then load the script.

What the cookie banner API is

The HubSpot tracking code defines two queues you can push commands to: _hsq for tracking and _hsp for privacy and consent. Like _hsq, _hsp is a plain array until HubSpot's script loads and then processes anything you pushed, so you can add commands early without worrying about load order.

var _hsp = window._hsp = window._hsp || [];

Always create the array defensively as shown, so your code works whether or not the banner script has loaded yet.

Listen for consent with addPrivacyConsentListener

The main command is addPrivacyConsentListener. You pass a callback, and HubSpot calls it with the visitor's current consent state, and again whenever that state changes.

var _hsp = window._hsp = window._hsp || [];
_hsp.push(['addPrivacyConsentListener', function (consent) {
  if (consent.allowed) {
    // visitor has made a choice that permits cookies
  }
  if (consent.categories && consent.categories.analytics) {
    // analytics cookies are allowed
  }
  if (consent.categories && consent.categories.advertisement) {
    // advertising cookies are allowed
  }
  if (consent.categories && consent.categories.functionality) {
    // functionality cookies are allowed
  }
}]);

The three categories, analytics, advertisement and functionality, match the categories shown in the banner. Check the specific category your script belongs to rather than only consent.allowed.

Load a script only after consent

Do not put the third-party script directly in the page. Instead, inject it from the listener, and make sure it is injected only once even if the listener fires several times.

var _hsp = window._hsp = window._hsp || [];
var analyticsLoaded = false;

function loadAnalytics() {
  if (analyticsLoaded) return;
  analyticsLoaded = true;
  var s = document.createElement('script');
  s.src = 'https://example.com/analytics.js'; // your vendor script
  s.async = true;
  document.head.appendChild(s);
}

_hsp.push(['addPrivacyConsentListener', function (consent) {
  if (consent.categories && consent.categories.analytics) {
    loadAnalytics();
  }
}]);

Note the limit of this approach: once a script is loaded it cannot be un-loaded without a page refresh. If a visitor withdraws consent, stop sending data on the next page view and, where the vendor offers one, call its opt-out method.

Let visitors change their mind

Under most privacy rules, withdrawing consent must be as easy as giving it. Two commands help with that:

  • _hsp.push(['showBanner']) reopens the banner so the visitor can change their selection.
  • _hsp.push(['revokeCookieConsent']) removes the visitor's stored consent choice.

A common use is a "Cookie settings" link in the footer:

<a href="#" id="cookie-settings">Cookie settings</a>
<script>
  document.getElementById('cookie-settings').addEventListener('click', function (e) {
    e.preventDefault();
    var _hsp = window._hsp = window._hsp || [];
    _hsp.push(['showBanner']);
  });
</script>

Where to put the code in HubSpot CMS

  • Site-wide: in Settings > Website > Pages > Templates (site header HTML), or in your theme's base template before the closing </head> or body, after {{ standard_header_includes }} / {{ standard_footer_includes }}.
  • Per module: in the module's module.js if only one component needs consent, for example an embedded map or video.

Remember the cookie banner itself is enabled and configured in HubSpot's settings (Settings > Privacy & Consent); the API only works with that banner, not with a separate consent tool such as Cookiebot.

Common mistakes

  • Loading the script first, then "blocking" it. If the tag is already in the page, it has already run. Inject it after consent instead.
  • Checking only consent.allowed. A visitor may accept analytics but refuse advertising. Check the category you need.
  • Not guarding against repeat calls. The listener can fire more than once, so use a flag to avoid loading the script twice.
  • Forgetting the banner on staging. Test on a domain where the banner is active, and test in a private window with cookies cleared.

How to test it

  1. Open the page in a private window and open the browser developer tools Network tab.
  2. Confirm your vendor script is not requested before you interact with the banner.
  3. Accept the relevant category and confirm the script is now requested once.
  4. Use your "Cookie settings" link to reopen the banner, change the choice and reload; confirm the script no longer loads when the category is refused.

Summary

Push addPrivacyConsentListener to _hsp, check the right category, and inject third-party scripts only from that callback. Add a footer link that calls showBanner so visitors can change their choice. This keeps your tracking aligned with the HubSpot cookie banner and your privacy policy. Always confirm the exact commands against HubSpot's current documentation on the cookie banner API, and have your legal advisor check your consent setup for your regions.

Related Articles