Embedding a Widget
A single hosted <script> include that handles the whole browser-widget flow from
Quickstart — registering the visitor, minting a session token, fetching the
active notice, showing a banner, and recording the decision — and actually blocks gated third-party
scripts/cookies until consent is granted, not just records that a decision happened.
Bring your own banner UI instead of the built-in one whenever you want (see Custom UI (headless mode) below) — either way, the registration/gating/blocking underneath is identical.
Setup
Add this as the first script in <head>, without async or defer:
<script src="https://api.bytemonk.co/widget/v1/consent.js" data-org-key="pub_9f8a1c2e..."></script>
Placement matters: the widget needs to see (and neutralize) gated scripts/iframes before anything else on the
page has a chance to run them. data-org-key is your org's Publishable key — never a Secret key here, same
rule as everywhere else in this API (see Authentication).
| Attribute | Required | Default | Purpose |
|---|---|---|---|
data-org-key | Yes | — | Publishable API key, identifies your org |
data-notice-group | No | cookie-consent | Which notice group to fetch/render |
data-lang | No | — | Force a specific notice language. Leave unset to let each visitor's own language dropdown pick (see Language selection) — a visitor's manual choice always wins over this, and this always wins over your org's Language Selection Strategy setting |
data-api-base | No | inferred from the script's own URL | Override only if you're proxying the API elsewhere |
data-headless | No | false | Skip the built-in banner — see below |
data-banner-position | No | bottom | bottom, top, bottom-left, or bottom-right — see below |
data-consent-mode-map | No | — | See Google Consent Mode v2 |
data-is-minor | No | false | Set to "true" if you already know the visitor is a minor — see Purposes restricted for minors |
Banner position
bottom (full-width bar) is the default, same as every other cookie banner provider. Override with
data-banner-position if you want a different placement:
<script src="https://api.bytemonk.co/widget/v1/consent.js"
data-org-key="pub_9f8a1c2e..." data-banner-position="bottom-right"></script>
| Value | Layout |
|---|---|
bottom (default) | Full-width bar, flush to the bottom of the viewport |
top | Full-width bar, flush to the top |
bottom-left | Compact box, anchored to the bottom-left corner |
bottom-right | Compact box, anchored to the bottom-right corner |
Below ~480px viewport width, every position collapses to the full-width bottom bar — a corner box has no room
to read as a "box" on a phone screen, which is why every provider that offers corner placement does the same
collapse. The detailed preferences panel (opened via "Manage Preferences") is always a centered modal regardless
of data-banner-position — that setting only affects the initial compact banner and the floating reopen button.
Language selection
The banner shows a language dropdown covering every language you've enabled on the notice. A visitor's own pick is remembered on their device and always wins on later visits.
Which language it opens in for a visitor who hasn't picked one yet is controlled from your dashboard, under Consent Management Settings → Language:
| Strategy | Behavior |
|---|---|
| Default language (default) | Always the notice's own configured default language |
| Visitor's state (India) | Resolved server-side from the visitor's own request — e.g. a visitor from Tamil Nadu opens in Tamil, from Kerala in Malayalam. Falls back to the default language if the state can't be resolved or has no clear majority language among the ones you've enabled |
| Visitor's device/browser language | Uses the visitor's own browser/OS language setting. Falls back to the default language if that language isn't one you've enabled on this notice |
data-lang (see Setup) overrides all of the above, and a visitor's own manual dropdown pick
overrides data-lang — both are more specific, deliberate choices than the org-wide default.
Gating scripts and iframes
Mark anything that shouldn't run before a purpose is granted by changing its type to text/plain and adding
data-consent-purpose:
<!-- External script, gated on the "analytics_cookies" purpose -->
<script type="text/plain" data-consent-purpose="analytics_cookies" src="https://www.googletagmanager.com/gtag/js"></script>
<!-- Inline script, same purpose -->
<script type="text/plain" data-consent-purpose="analytics_cookies">
window.dataLayer = window.dataLayer || [];
function gtag(){ dataLayer.push(arguments); }
gtag('js', new Date());
gtag('config', 'G-XXXXXXX');
</script>
<!-- Embedded iframe, gated on "advertising_cookies" -->
<iframe data-consent-purpose="advertising_cookies" data-src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe>
data-consent-purpose must match a purposeCode from your org's own published notice — this isn't a fixed
necessary/analytics/marketing taxonomy, it's whatever purposes you configured in the CMP dashboard. A
<script type="text/plain"> never executes on its own (browsers only auto-run text/javascript or scripts with
no type), so anything tagged this way stays completely inert until the widget activates it — there's no window
where a gated script can slip through before the check runs.
Cleaning up cookies a script already set
If a purpose is later denied or withdrawn, the widget can't know what cookies a third-party script already set
unless you tell it. Add data-cookie-names (comma-separated, trailing * for a prefix match) to the same tag:
<script type="text/plain" data-consent-purpose="analytics_cookies"
data-cookie-names="_ga,_ga_*,_gid"
src="https://www.googletagmanager.com/gtag/js"></script>
Without this attribute, cookies already set by a script before it was denied are left alone — there's no safe way to guess a third-party script's cookie names, so nothing here tries to.
Consent flow
The widget handles registering (or resolving) the visitor as a Data Principal, minting a session token from the
stored principalSecret, fetching the active notice, showing a banner if no valid decision exists yet, and
calling /consent/grant or /consent/withdraw when the visitor acts — the full flow already described in
Quickstart. A small floating "Cookie Preferences" button appears once a decision
has been made, so the visitor can reopen and change it later — consent has to be as easy to withdraw as it was to
give.
principalSecret is stored once in localStorage and never re-requested — see
Data Principals → Principal secrets for why it exists and
what happens if a visitor clears their storage. The session token itself is only kept in memory, re-minted on
every page load — it's cheap to re-mint and expires in 15 minutes anyway.
The widget also calls Record a notice view for you automatically, right when it determines a decision prompt is actually warranted (first visit, or a purpose needs re-consent) — never for an already-decided visitor whose banner stays hidden. This is purely an analytics signal (feeds conversion reporting on the admin dashboard); nothing to configure, and no effect on the consent flow itself. Only relevant if you're building a fully custom banner instead — see that endpoint's own docs for when to call it.
Re-consent when your notice changes
Handled automatically, per purpose — not "does the notice version match." If you publish a new notice version that adds a purpose or changes an existing one's terms, a returning visitor sees a banner naming specifically what changed ("We've updated how we use your data (Advertising). Please review and confirm your choices.") while any unaffected purpose they already decided on carries forward silently, with no reprompt. Republishing a notice for a reason that doesn't change any purpose (a copy-editing fix to the notice text, for example) never triggers a reprompt at all, even though the notice gets a new version. See Versioning Notices if you're building a custom integration instead of using this widget and need to replicate the same per-purpose logic yourself.
Purposes restricted for minors
A purpose flagged restrictedForMinors (see Consent Notices → Purposes)
is enforced server-side unconditionally — DPDPA Sec 9(3) prohibits tracking/behavioral monitoring/targeted
advertising directed at children regardless of consent, so this can never be granted for a minor, even with
verified guardian consent on file. The widget only enforces this if it knows the visitor is a minor, and it
has no way to determine that on its own — there's no age-verification step built into the banner. This matches
how consent platforms generally handle it: age determination happens wherever your own site already knows it
(a login/account system, or a site-wide "this is a children's product" flag), not inside a cookie banner.
If you already know at page load:
<script src="https://api.bytemonk.co/widget/v1/consent.js"
data-org-key="pub_9f8a1c2e..." data-is-minor="true"></script>
If you only find out asynchronously (e.g. after your own login check resolves), call this before the visitor's first decision. The widget only registers a visitor (creates a Data Principal) when they first accept, reject or save preferences, not when the page loads, and there's no way to retroactively flag an already-registered principal as a minor:
window.BytemonkConsent.setMinor(true);
When set, restricted purposes render disabled with a "Not available" label in the preferences panel (instead of a toggle that looks selectable but is silently denied server-side either way), and "Accept All" excludes them from what it grants.
Custom UI (headless mode)
Add data-headless="true" to skip the built-in banner entirely — gating, script/iframe activation, cookie
purge, and Consent Mode signals all still work exactly the same; only the banner DOM is skipped. Build your own
banner (React, Vue, plain HTML, whatever) off the bytemonkNoticeReady event and call
window.BytemonkConsent.grant(...) when the visitor decides:
<script src="https://api.bytemonk.co/widget/v1/consent.js"
data-org-key="pub_9f8a1c2e..." data-headless="true"></script>
<script>
document.addEventListener("bytemonkNoticeReady", (e) => {
renderMyOwnBanner(e.detail.notice); // e.detail.notice.purposes -> whatever you need to render
});
function onVisitorAccepts(purposeSelections) {
window.BytemonkConsent.grant(purposeSelections); // e.g. { analytics_cookies: true, advertising_cookies: false }
}
</script>
This is the entire integration surface for a fully custom banner — everything else (registration, token minting, notice fetching, gating, activation) is handled identically to the default mode; headless mode only opts out of this file's own banner DOM/CSS.
Public JS API
window.BytemonkConsent.get('analytics_cookies'); // true / false / undefined (no decision yet)
window.BytemonkConsent.getAll(); // { analytics_cookies: true, advertising_cookies: false, ... }
window.BytemonkConsent.getNotice(); // the active notice, or null before it loads
window.BytemonkConsent.grant({ analytics_cookies: true }); // record a decision (used internally by the built-in banner too)
window.BytemonkConsent.withdraw('analytics_cookies'); // withdraw just one purpose (omit the arg to withdraw all)
window.BytemonkConsent.setMinor(true); // see "Purposes restricted for minors" above -- call before registration
window.BytemonkConsent.showPreferences(); // re-opens the built-in banner (no-op in headless mode)
document.addEventListener('bytemonkConsentUpdated', (e) => {
// e.detail.noticeId, e.detail.purposeSelections
// Fires on initial load (from a stored decision) and every time the visitor changes their choice.
});
document.addEventListener('bytemonkNoticeReady', (e) => {
// e.detail.notice -- fired once the active notice loads, in both default and headless mode.
});
Google Consent Mode v2
If you use Google Tag Manager/GA4/Google Ads, set data-consent-mode-map on the widget's own script tag to a
JSON object mapping your purpose codes to Consent Mode signal names:
<script src="https://api.bytemonk.co/widget/v1/consent.js"
data-org-key="pub_9f8a1c2e..."
data-consent-mode-map='{"analytics_cookies":"analytics_storage","advertising_cookies":["ad_storage","ad_user_data","ad_personalization"]}'>
</script>
The widget pushes gtag('consent', 'default', {...denied...}) immediately on load (before your GTM container
script has a chance to fire anything), then gtag('consent', 'update', {...}) the moment a real decision exists.
This is the mechanism GTM/GA4 expect for consent-aware tag firing — configure your GTM tags' consent settings to
respect these signals rather than relying on the widget to intercept GTM's own internal script injections
directly (see the limitation below).
Other tag managers (Tealium, Adobe Launch, Segment, etc.)
There's no built-in data-*-map attribute for these the way there is for Google Consent Mode — but the
underlying mechanism is the same. Listen for bytemonkConsentUpdated (or call window.BytemonkConsent.getAll()
directly, same data) and translate our purpose codes into whatever consent API your tag manager expects. This is
exactly what the widget does internally for data-consent-mode-map — it's just not pre-written for other vendors.
document.addEventListener('bytemonkConsentUpdated', (e) => {
const d = e.detail.purposeSelections; // { analytics_cookies: true, marketing_communications: false, ... }
// translate into your vendor's consent API — exact call depends on how that vendor's
// consent module is configured on your account, so treat the snippets below as a starting point, not a
// drop-in.
});
Tealium (illustrative):
document.addEventListener('bytemonkConsentUpdated', (e) => {
const d = e.detail.purposeSelections;
utag.gdpr.setConsentCategories({
analytics: !!d.analytics_cookies,
marketing: !!d.marketing_communications,
});
});
Adobe Launch / AEP (illustrative):
document.addEventListener('bytemonkConsentUpdated', (e) => {
const d = e.detail.purposeSelections;
window.adobeDataLayer.push({
event: 'consentUpdate',
consent: { analytics: d.analytics_cookies, marketing: d.marketing_communications },
});
});
This adapter is typically 5-10 lines regardless of vendor. If a particular vendor comes up often enough, it's a
candidate for a purpose-built data-*-map attribute like the GTM one, rather than a snippet every integrator
writes by hand.
Known limitation: tag manager-injected scripts
The type="text/plain" gating mechanism only catches scripts that exist as literal <script> tags in your page
HTML. A tag manager (GTM, Tealium, Adobe Launch, Segment, etc.) that injects its own additional scripts at
runtime — outside anything this widget can see in advance — isn't caught by DOM scanning alone. This isn't unique
to this widget; it's inherent to how any CMP integrates with any tag manager. Two ways to handle it:
- Preferred: wire the tag manager's own consent-aware tag settings to the signal this widget emits — Consent
Mode (above) if it's GTM/GA4, or the
bytemonkConsentUpdatedadapter (above) translated into that vendor's own consent API otherwise. Most major tag managers respect their own consent signal natively once a tag is configured to require it. - Gate the tag manager's own top-level
<script>tag itself withtype="text/plain"+data-consent-purposeif you want the entire container to not load at all pre-consent, rather than loading it and depending on its internal tags to self-gate.