Developer docs

Get CookieGuard live in three lines.

Everything you need to install, configure, and operate the CookieGuard script. If something is missing, ping cjakciasteczko@aveneo.pl.

Installation

Paste this snippet inside your <head>, before any third-party tag (Google Analytics, Meta Pixel, LinkedIn Insight, …). Order matters — CookieGuard pushes Google Consent Mode v2 defaults to denied the moment it parses, and any tag loaded after will read those defaults.

<script>
  window.CookieConsentConfig = {
    domain: "yourdomain.com",
    theme: { primary: "#0F62FE" },
    language: "auto",
    geoMode: "eea-strict"
  };
</script>
<script async src="https://cjakciasteczko.pl/v1/cjakciasteczko.js"></script>

That's it. The banner appears on first visit, the visitor's decision is persisted, and Google Consent Mode v2 signals propagate automatically.

Configuration schema

Every key is optional except domain. Defaults are sane — most customers ship with just the snippet above.

Field	Type	Default	Notes
`domain`	string	—	Required. Your hostname.
`layout`	"banner" \| "modal" \| "floating"	`"modal"`	Banner shape.
`position`	5 options	`"center"`	top / bottom / center / bottom-left / bottom-right.
`language`	"auto" \| "en" \| "pl" \| "de"	`"auto"`	Falls back to navigator.language.
`geoMode`	"eea-strict" \| "eea-only" \| "off"	`"eea-strict"`	Where to enforce opt-in.
`theme.primary`	hex	`#0F62FE`	CTA + accent color.
`theme.background`	hex	`#FFFFFF`
`theme.text`	hex	`#161616`
`theme.radius`	number (px)	`12`	Card corner radius.
`theme.shadow`	"none" \| "sm" \| "md" \| "lg"	`"lg"`
`theme.logoUrl`	URL	—	Shows above the title.
`theme.animation`	5 options	`"fade"`	fade / slide-up / slide-down / scale / none.
`policyUrl`	URL	—	Linked from the banner body.
`consentVersion`	integer	`1`	Bump to force re-consent.
`consentDurationDays`	integer	`365`	How long a decision sticks.
`googleConsentMapping`	object	see below	Maps categories → GCMv2 signals.
`reportUrl`	URL \| `false`	auto	Where to send consent records. Auto-derived from script src.

Google Consent Mode v2 mapping (default)

googleConsentMapping: {
  ad_storage:              "marketing",
  ad_user_data:            "marketing",
  ad_personalization:      "marketing",
  analytics_storage:       "analytics",
  functionality_storage:   "necessary",
  personalization_storage: "preferences",
  security_storage:        "necessary"
}

JavaScript API

The script exposes window.cookieguard after the loader finishes. Wait for it via ready() if you need to call it on page load.

// Wait until ready
await window.cookieguard.ready();

// Read consent state
const allowed = window.cookieguard.getConsent("analytics"); // true | false
const record  = window.cookieguard.getConsentState();       // ConsentRecord | null

// React to changes
const off = window.cookieguard.onConsentChange((rec) => {
  console.log("user changed consent:", rec.choices);
});
// off()  to unsubscribe

// Imperative
window.cookieguard.showBanner();        // open the consent banner
window.cookieguard.showPreferences();   // open the preferences modal
window.cookieguard.revoke();            // clear stored consent

window.cookieguard.version;             // "0.0.1"

A typical pattern is to gate non-essential scripts ononConsentChange rather than on page load — that way you react when the user later opens preferences and changes their mind.

Google Tag Manager

For GTM users, install CookieGuard via a Custom HTMLtag that fires on Consent Initialization — All Pages. That trigger fires before everything else, which guarantees the denied defaults land before any pixel.

GTM → Container Settings → enable Consent Overview.
Tags → New → Custom HTML. Paste the snippet from Installation.
Triggering → Consent Initialization — All Pages.
For each existing tag (GA4, Meta Pixel, …) open its Consent settings and add the matching required consent values from the table in Configuration.

For a deeper walkthrough see the blog: How to install a CMP via Google Tag Manager.

WordPress & Shopify

A native WordPress plugin and Shopify app are on the immediate roadmap. Until then, paste the snippet via:

WordPress — Appearance → Theme File Editor → header.php, before </head>. Or use any “Header & Footer Scripts” plugin.
Shopify — Online Store → Themes → Edit code → theme.liquid, before </head>.
Webflow — Project Settings → Custom Code → Head code.
Wix / Squarespace — Settings → Custom Code → Head.

Webhooks & consent records

Every time a visitor saves a decision, the script POSTs an event toPOST /api/consent on your CookieGuard origin. You can:

View each record in Dashboard → Domain → Consent records
Export as CSV or NDJSON from the same screen
Verify the hash chain — every row links to the previous via prevHash / thisHash (SHA-256), so any mid-row tamper breaks the chain

Outbound webhooks (push to your endpoint on every consent event) are on the roadmap. Until then, poll the export endpoint or query the consent-records page directly.

Troubleshooting

The banner doesn't appear

Check the browser console for [CookieConsent] window.CookieConsentConfig.domain missing.
Some ad-blockers block CMPs. Check the network tab — if cookieguard.js is blocked, the issue is on the visitor's side, not yours.
If you previously consented, the banner is suppressed. Open DevTools > Application > Local Storage, delete the cg_consent_v1::* key, and reload.

Tag fires before consent is granted

Make sure your tag's Consent settings in GTM list the matching analytics_storage / ad_storage requirement.
The wait_for_update: 500 default gives your CMP 500ms — if your script loads slower than that, increase it in the snippet.

I'm getting CORS errors on the `/api/consent` endpoint

The endpoint sets Access-Control-Allow-Origin: *. If you still see errors, double-check that your hostname is registered in the dashboard exactly as it appears in the browser URL bar.