Developer Reference: Captain Compliance Events, Cookies, and Identifiers

Edited

This reference collects the names developers need when integrating with the Captain Compliance consent banner: the script, data layer events, cookies, Google Tag Manager (GTM) names, and page elements. Each section links to the article that explains the item in context.

Banner script

Each domain has its own script, identified by an access token. Copy it from the app rather than typing it.

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

Add the defer attribute to run the script after the initial page load. See How to Publish a Consent Banner on Your Website.

To serve the banner in one fixed language, add the language-code attribute, for example language-code="es". The app also provides Next.js and React snippets under Setup → Installation script.

Data layer events

The banner pushes these events to the data layer.

Event

When it is pushed

Payload

captainComplianceConsent

On page load when a stored choice exists, and again whenever the state changes

The active model and a selectedCookies object with one boolean per category

captainComplianceConsentUpdated

When the visitor makes or changes a choice in the banner

Same as above

captainComplianceConsentReady

Once the banner has resolved the visitor’s effective state for the page (regional default, stored preference, and Global Privacy Control)

None. It marks the moment the state is known

See How to Gate GTM Tags with Captain Compliance Consent Events (Advanced) and How to Fire Early-Loading Tags After Consent with CC - Consent Ready.

Consent categories

Category

Data layer key

Google Consent Mode signals

Strictly Necessary

None (always granted)

security_storage

Functionality

selectedCookies.FUNCTIONALITY_COOKIES

functionality_storage, personalization_storage

Performance

selectedCookies.PERFORMANCE_COOKIES

analytics_storage

Targeting

selectedCookies.TARGETING_COOKIES

ad_storage, ad_user_data, ad_personalization

See How Captain Compliance Works with Google Consent Mode.

Cookies

Cookie

Purpose

cc_consent_preference

Stores the visitor’s consent choice

cc_region_defaults

Caches the regional default so it can be applied immediately from the next page view

cc_consent_cc-modal-user-location

Stores the visitor’s detected location (country, region, and state or province code), which is used to choose the banner configuration

The banner can also set other cookies whose names start with cc_, such as cc_global_consent, which holds the choice for the domain and for the subdomains that share it. Between test runs, clear every cookie whose name starts with cc_, or open a new private window. A banner that has been closed also stays hidden until the browser tab is closed. See How to Test Your GTM Consent Setup.

Google Tag Manager names

Name

Type

Purpose

Captain Compliance CMP

Tag template

Loads the banner, sets Google Consent Mode defaults, and honors Global Privacy Control

CaptainGPCSignalDetected

Custom JavaScript variable

Passes the browser’s Global Privacy Control flag to the template

CC - Consent Ready

Custom Event trigger

Fires on captainComplianceConsentReady, for early-loading tags that require consent

CC - Performance granted, CC - Targeting granted, CC - Functionality granted

Data Layer Variables (version 2)

Read each category’s value from selectedCookies

See How to Install and Configure the Captain Compliance CMP Template in GTM and How to Integrate Google Tag Manager (GTM) with Captain Compliance.

Page elements

Any element with the ID id-open-settings-cc opens the consent preferences interface when clicked.

<a href="#" id="id-open-settings-cc">Cookie Preferences</a>

See How to Add a “Cookie Preferences” Option to Your Website Footer.

Execution-gating helper

For scripts that GTM does not control, the helper exposes a CaptainCompliance object with the functions below. Its code is included in the linked article. The category is PERFORMANCE, TARGETING, or FUNCTIONALITY.

  • CaptainCompliance.executeIfConsent(category, callback) runs the callback only if the category is granted.

  • CaptainCompliance.loadScriptIfConsent(category, url) loads a script only if the category is granted.

  • CaptainCompliance.hasConsent(category) returns true if the category is granted.

  • CaptainCompliance.getConsentStatus() returns the overall status stored with the visitor’s choice, or null if no choice is stored.

  • CaptainCompliance.onConsentChange(callback) calls the callback when the stored choice changes.

See How to Gate Non-Essential Scripts and Beacons Using Explicit Consent Logic.

Script blocking attributes

In Strict mode, a script that is held until consent appears in the page with the attributes below.

<script
  type="text/plain"
  data-cc-category="TARGETING_COOKIES"
  data-cc-src="https://example.com/script.js">
</script>

The data-cc-category values are STRICTLY_NECESSARY_COOKIES, FUNCTIONALITY_COOKIES, PERFORMANCE_COOKIES, TARGETING_COOKIES, and UNCLASSIFIED_COOKIES. See How to Block Scripts Before Consent with Auto Blocking and Strict Mode.

Cookie deletion endpoint

Under Setup → API configuration, you can register an endpoint on your own server for what the app calls the Cookie Deletion Service. The endpoint receives a POST request whose body lists cookies by name, domain, and a matching pattern.

{
  "cookieList": [
    { "name": "cookie_name_1", "domain": "example.com", "regex": "^cookie_name_1
quot; }, { "name": "cookie_name_2", "domain": "example.com", "regex": "^cookie_name_2
quot; } ] }

Use Test Endpoint to check the response, and then select Save Endpoint. Protect the endpoint against cross-site request forgery, and add authentication if your setup requires it.

DSR portal embed

A data subject request portal can be linked or embedded. The hosted portal is at https://dsar.cptn.co/dsar/YOUR_ACCESS_TOKEN. To embed it, add the script and the container element. Copy both from DSR Portal Script in the app.

<script
  src="https://api-prod.cptn.co/requestForm/script"
  access-token="YOUR_ACCESS_TOKEN">
</script>

<div id="captain_compliance_form_container"></div>

See How to Generate and Customize a Data Subject Request (DSR) Portal.

Network origins

Origin

Used for

*.cptn.co

The banner script, API requests, consent records, styles, and assets

api.ipify.org

The public IP lookup used for jurisdiction detection

privacy.cptn.co

Hosted privacy notices

dsar.cptn.co

Hosted DSR portals

*.cookietransparency.com

Hosted cookie transparency pages

See How to Configure a Content Security Policy (CSP) for Captain Compliance and How to Embed Your Privacy Notice Using an iFrame.

Banner JavaScript object

The banner script adds a CaptainConsent object to the page. Use it in code that runs after the banner script. It is separate from the CaptainCompliance helper described above.

  • CaptainConsent.getConsentState() returns the visitor’s current decision. The result includes hasDecision, status (ALLOWED, REJECTED, PARTIALLY_ALLOWED, or GPC_APPLIED), categories, and notSellPersonalInfo.

  • CaptainConsent.on('consentChanged', callback) calls the callback when the visitor makes or changes a choice. The callback receives marketing, analytics, preferences, and sale_of_data as true or false.

  • CaptainConsent.getShopifyConsent() returns the stored choice as Shopify’s four consent values, or null if no choice is stored.

  • CaptainConsent.isShopifyStore() returns true when Shopify’s Customer Privacy API is available on the page.

See How Captain Compliance Syncs Consent with the Shopify Customer Privacy API.

Debug mode

Add ?cc_debug=true to a page address and reload. The banner script then writes its steps to the browser console, in lines that start with [CC]. See How to Troubleshoot a Consent Banner That Does Not Appear or Respond.

Related articles