Client API, events and the command queue

This page is the reference for what the core script puts on your page: the globals, the client methods, the events on document, and the window.noxtica(...) command queue. Use it when you wire a consent banner, react to a step-up challenge, or queue calls before the script has loaded.

What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation.

A core tag with data-auto-init builds one client for the page. The client, the events and the command queue exist on tags that carry data-auto-init. A client you create with NoxticaCollector.createClient() returns its results through promises and does not fire noxtica:ready. See Script attributes and client options.

Until the extensions script attaches, the core runs a reduced lane. When the extensions attach, every public method of the client delegates to the extensions runtime; the core keeps loadExtensions, getExtensionsState and destroy. Loading the extensions never grants consent; see Consent modes.

Prerequisites

• The core tag with data-site-key and data-auto-init, as generated by Backoffice → Integrations & API → Script & Consent → Snippets.
• Your listeners registered before the core tag runs. Put them in an inline script in <head> above the tag. An event that already fired is not replayed.
• Your own consent flow, if the domain uses the api mode: your page calls setConsent. See Consent modes.

Steps

1. Read the page globals

2. Call the client methods

Page check and state

Lifecycle

Consent and extensions

Protected actions, identity and events

The client object has more members, such as tracker and token-refresh controls. They are internal and not supported.

3. Listen to events

All events are dispatched on document with a CustomEvent. Register the listeners in <head> before the core tag:

<script>
	document.addEventListener('noxtica:collected', (event) => {
		if (event.detail.skipped === 'consent_required') return; // not an error
		// Hand event.detail.fingerprintId to your backend as a hint, not as an identity.
	});
	document.addEventListener('noxtica:error', (event) => {
		console.warn('Noxtica reported', event.detail.source, event.detail.message);
	});
	document.addEventListener('noxtica:challenge', (event) => {
		// event.detail: { status: 'started' | 'solved' | 'failed' | 'unsupported', method: 'gpu-pow' | 'turnstile' }
	});
	document.addEventListener('noxtica:block', (event) => {
		// event.detail: { status: 'blocked' | 'redirected' | 'failed', mode: 'overlay' | 'redirect' }
	});
</script>

noxtica:challenge and noxtica:block fire when the server issues a challenge or a block for the visit, and not otherwise. Whether your domain can issue them depends on your configuration. The page acts on a block directive when the signed result verifies and carries the same block id, so a forged directive does nothing.

With createClient options onChallenge and onBlock you get the same details through callbacks. A callback that throws never breaks collection.

noxtica:extensions-* details were strings before SDK 3.8.0. Read detail.message for the old value.

4. Queue calls before the script loads

The command queue follows the gtag pattern. Define the stub above the core tag, then call it:

<script>
	window.noxtica = window.noxtica || function () { (window.noxtica.q = window.noxtica.q || []).push(arguments); };
	noxtica('consent', 'gcm');
	noxtica('set', 'plan', 'pro');
</script>
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-auto-init
	data-auto-check-once
	async
></script>

An array assigned to window.noxtica also works as a stub. The core replays the queued calls in order against the initial client it creates, then replaces the stub with a live function. Later calls, and a stub reference you kept, run at once and return the method’s result.

These are the 14 commands. Behaviour to rely on:

• An unknown command logs a warning and does nothing. A command that fails reports noxtica:error and never throws.
• Queued setConsent and consent updates are folded into one update, applied where the earliest of them stood (a later key wins), so you get one noxtica:consent-changed. A queued loadExtensions is dropped when the folded state denies all four categories. This applies to loader 3.8.1 and later; earlier loaders replayed every call in order.
• If window.noxtica is a plain object without a q array, the loader leaves it untouched and the commands are unavailable.
• Deciding consent in a noxtica:ready handler is more robust than queuing it. See Events and timing.

5. Read the checkOnce result

A numeric score, risk_level and confidence may be absent when the server withholds them. Treat a missing score as unknown, never as zero.

Verify it works

Open the console on a page that has the tag and consent decided:

window.noxticaClient.getConsent();        // { mode, modeResolved, analytics, replay, deviceId, behavioral, privacySignal }
window.noxticaClient.getExtensionsState(); // 'not-loaded' before the extensions attach, 'attached' after
window.noxticaResult;                      // the last result announced with noxtica:collected
window.noxtica.v;                          // the loader version
await window.noxticaClient.getToken();     // a token string once /client/token succeeded

Add a temporary listener for each event in step 3 and reload. A healthy consented page logs noxtica:ready, then noxtica:consent-changed and noxtica:extensions-loaded after your consent call, then noxtica:collected.

Troubleshooting

Related

• Script attributes and client options: the options that configure the client.
• Consent modes, GPC and Google Consent Mode: categories, precedence and the Google bridge.
• Protected actions: protect(), noxtica:protected and the server check.
• Install and Browser Runtime: events and timing, extension load reasons.
• Custom events, session tags and request tracing: the session API in depth.
• Browser SDK troubleshooting: symptoms across the SDK.