---
title: "Script attributes and client options"
description: "Every data-* attribute on the Noxtica script tag and every createClient or init option, with accepted values, defaults and effect."
canonical_url: "https://noxtica.com/docs/sdk/script-attributes/"
markdown_url: "https://noxtica.com/docs/sdk/script-attributes/index.md"
last_updated: 2026-10-27
published: 2026-10-27
section: "browser-sdk"
section_title: "Browser SDK"
site: "Noxtica"
language: "en"
source: markdown
---

# Script attributes and client options

This page lists every setting you can put on the Noxtica script tag and every option you can pass to `createClient()` or `init()`, with the accepted values, the default and what each one changes. Use it when you edit the generated tag, wire the collector from your own code, or review a tag someone else pasted.

## What it is

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

The browser collector has two entry points:

- **The script tag.** The core script reads `data-*` attributes from its own tag when the page has loaded. Backoffice → Integrations & API → Script & Consent → Snippets generates the tag with your Site Key. Install and consent concepts stay on [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- **Client options.** `window.NoxticaCollector.createClient(options)` takes the same ideas as an object, plus callbacks that an attribute cannot carry (`onChallenge`, `onBlock`). The typed `@noxtica/sdk` wrapper has an `init(config)` function that forwards a subset of these options. That wrapper is not installable from the public registry today; see [SDK family and availability](https://noxtica.com/docs/sdk/family/).

The loader reads the attributes once, when the tag initialises. Changing an attribute afterwards has no effect until the next page load. A value the loader cannot parse is ignored and never breaks collection.

## Prerequisites

- A domain with a Site Key. Backoffice → Domains lists the key; see [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).
- A page served from the origin registered for that Site Key. A token request from another origin is refused with `403` and `{"error":"Origin mismatch"}`.
- Workspace admin access to Backoffice → Integrations & API → Script & Consent, if you want to copy the generated tag instead of typing it.
- The core script URL on your collector host: `https://collect.noxtica.com/collector/noxtica-collector-core.js`. The extensions script takes no attributes and no Site Key; it attaches to the core on the page.

## Steps

### 1. Start from the generated tag

Open Backoffice → Integrations & API → Script & Consent, pick the domain, and copy the core snippet from the **Snippets** tab. Two switches on that tab add attributes for you: **Add data-extensions="auto" to the core snippet** and **Add data-consent-mode="api" to the core snippet**.

```html
<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>
```

Keep the file name. The loader binds a tag when its `src` contains `noxtica-collector` or `/noxtica.js` and the tag carries `data-auto-init`; a tag that misses either condition is ignored. This matters when you copy the script to your own path or serve it through a [first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/).

### 2. Set the attributes you need

| Attribute | Accepted values | Default | Effect |
| --- | --- | --- | --- |
| `data-site-key` | Your Site Key | none, required | A tag without it is skipped: no client, no events. The key works on the origin registered for its domain. |
| `data-auto-init` | Boolean attribute | off | Creates the client for this tag, assigns `window.noxticaClient`, runs the `window.noxtica` command queue, then dispatches `noxtica:ready`. Without it the loader does nothing by itself. |
| `data-auto-check-once` | Boolean attribute | off | After `noxtica:ready`, runs `checkOnce()` once per page load and announces the result with `noxtica:collected`. Recommended. |
| `data-auto-collect` | Boolean attribute | off | Legacy. Runs `collectAndSubmit()` on every page load, without the cache. Ignored when `data-auto-check-once` is also present. |
| `data-ttl-seconds` | Positive integer | none | Cache window in seconds for the automatic check. Read together with `data-auto-check-once`; without that attribute it has no effect. Zero, negative and non-numeric values are ignored. |
| `data-check-interval-days` | Positive number | none | Cache window in days for every `checkOnce()` call of this client. Zero, negative and non-numeric values are ignored. |
| `data-api-url` | `https` URL, or any URL on `localhost` or `127.0.0.1` | `https://collect.noxtica.com` | Collector origin for the token, submit and visit calls. Any other value is ignored and a warning is logged. |
| `data-ingest-url` | `auto`, or an `https` URL (or a localhost URL) | `auto` | Origin for high-volume telemetry: RUM, RUM error detail, console logs, the client buffer, and the replay policy and upload calls. The interaction tracker stays on the collector. `auto` derives `https://ingest.noxtica.com` from the default collector host and keeps any other `data-api-url` host for telemetry too. An explicit URL wins; set it to the collector origin to keep telemetry on the collector. An invalid value is ignored and a warning is logged. |
| `data-consent-mode` | `api`, `cookie:<name>`, `cookie:<name>=<value>`, `gcm`, `not_required` | none | Declares the consent mode before the signed token arrives. A declaration can make the client stricter; it never relaxes the mode saved for the domain. See [Consent modes](https://noxtica.com/docs/sdk/consent/). |
| `data-consent-cookie` | `<name>` or `<name>=<value>` | none | Shorthand for `data-consent-mode="cookie:<name>"`. Ignored when `data-consent-mode` is present and valid. |
| `data-extensions` | `auto` | manual | `auto` makes the core load the extensions script itself. Any other value keeps the extensions manual, and overrides the automatic default of the legacy script URLs. The domain setting **Load the extensions script automatically once consent is granted (immediately in Not required mode)** still applies. |
| `data-log-level` | `silent`, `error`, `warn`, `info`, `debug` | see step 5 | Highest-precedence console log level. An invalid value is ignored. |
| `data-debug` | Boolean attribute | off | Legacy switch. Behaves like log level `debug` when no explicit level is set anywhere. |
| `data-debug-upload` | Boolean attribute | off | Diagnostic. Replay chunk and finalize uploads are captured on the page instead of being sent. Do not leave it on in production. |
| `integrity`, `crossorigin="anonymous"` | SRI hash, as generated | none | The pinned variant of the tag. See [Stable or pinned snippets](https://noxtica.com/docs/browser-runtime/#stable-or-pinned-snippets). |
| `async` | Boolean attribute | none | Lets the page render while the core loads. |

Two attributes go on your own forms, not on the script tag:

| Attribute | Where | Default | Effect |
| --- | --- | --- | --- |
| `data-nox-protect="<action>"` | A form, or a button or input inside one | none | Runs the protected-action check for the named action. The action must be declared for the domain. See [Protected actions](https://noxtica.com/docs/sdk/protected-actions/). |
| `data-nox-protect-timeout="<ms>"` | The same form | `6000` | How long a native form submit is held while the check runs. A value that is not a positive integer falls back to the default. |

### 3. Choose how often the page check runs

`checkOnce()` returns the cached result while the cache window is open and records a visit instead of collecting again. The loader picks the window in this order, and the earliest match wins:

1. `ttlSeconds` in the call. For the automatic check this is `data-ttl-seconds`.
2. `checkIntervalDays` in the call.
3. The client option `checkIntervalDays`, which `data-check-interval-days` sets.
4. The `checkIntervalDays` value in the domain policy delivered with the session token.
5. Seven days.

Call options for `checkOnce(options)`:

| Option | Default | Effect |
| --- | --- | --- |
| `ttlSeconds` | none | Cache window in seconds for this call. |
| `checkIntervalDays` | none | Cache window in days for this call. |
| `forceRefresh` | `false` | Clears the stored state and collects again. |
| `recordVisit` | `true` | Records a visit on a cache hit. With `false` the cached result comes back with `visitRecorded: false`. |
| `meta` | none | Metadata passed with the visit record. |

### 4. Create a client from code

Use `createClient` when a tag with `data-auto-init` does not fit, for example when your page decides at run time whether to start Noxtica. A client you create yourself does not set `window.noxticaClient`, does not dispatch `noxtica:ready` and does not read the command queue. Its results come back through the promises it returns.

```html
<script>
	const tag = document.createElement('script');
	tag.src = 'https://collect.noxtica.com/collector/noxtica-collector-core.js';
	tag.async = true;
	tag.onload = () => {
		const client = window.NoxticaCollector.createClient({
			siteKey: 'pk_prod_your_site_key_here',
			consentMode: 'api',
			logLevel: 'silent',
		});
		client.checkOnce().then((result) => console.log(result.success));
	};
	document.head.appendChild(tag);
</script>
```

`createClient` throws `NoxticaCollector: siteKey is required` when it finds no Site Key, either in the `siteKey` option or on a collector tag with `data-site-key`.

| Option | Type and default | Effect |
| --- | --- | --- |
| `siteKey` | string | Your Site Key. Falls back to the `data-site-key` of a collector tag on the page. |
| `apiUrl` | `https` URL, default `https://collect.noxtica.com` | Collector origin. |
| `ingestUrl` | URL or `'auto'`, default `'auto'` | Telemetry origin; same rules as `data-ingest-url`. |
| `mode` | `'max'` (default) or `'lite'` | `max` collects the full signal set. `lite` skips the collectors that belong to `max` mode. Protected actions always run in minimal mode. |
| `checkIntervalDays` | number | Client-level cache window. |
| `signatureMode` | `'require'` (default), `'warn'`, `'disabled'` | What the client does when a signed server response is missing or altered. `require` rejects it, `warn` logs and continues, `disabled` skips the check. An unknown value falls back to `require`. Keep `require`. |
| `accountId` | string, up to 256 characters | Your own end-user account id, sent with the next submit. Use an opaque id, not an e-mail address. `client.setAccountId(id)` sets it later. |
| `consentMode` | `'api'`, `'cookie:<name>'`, `'cookie:<name>=<value>'`, `'gcm'`, `'not_required'` | Same as `data-consent-mode`. |
| `extensions` | `'auto'` | Same as `data-extensions="auto"`. |
| `logLevel` | `'silent'`, `'error'`, `'warn'`, `'info'`, `'debug'` | Same as `data-log-level`, one precedence step lower. |
| `debug` | boolean | Legacy form of log level `debug`. |
| `debugUploads` | boolean | Same as `data-debug-upload`. |
| `onChallenge` | function | Called with `{ status, method }` while the server asks for a step-up challenge. Advisory. |
| `onBlock` | function | Called with `{ status, mode }` when the page enforces a server block. Advisory. |
| `release`, `buildId`, `subjectHandle` | strings | Labels for browser error detail. They take effect when the extensions are loaded. See [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/). |

The wrapper's `init(config)` accepts `siteKey`, `apiUrl`, `ingestUrl`, `mode`, `checkIntervalDays`, `signatureMode`, `accountId`, `debug`, `logLevel`, `onChallenge`, `onBlock`, `release`, `buildId`, `subjectHandle` and `observability`, plus options that are specific to the wrapper:

| Wrapper option | Default | Effect |
| --- | --- | --- |
| `script` | `'core'` | `'core'` injects the core script. `'combined'` injects the legacy combined script. |
| `extensions` | `'manual'` | `'manual'` waits for `loadExtensions()`. `'auto'` lets the core load them. `'never'` makes `loadExtensions()` reject, and cannot be combined with `script: 'combined'`. |
| `scriptUrl`, `pinnedLoader` | none | Inject a pinned core: set `scriptUrl` to the hashed file name from the collector manifest and `pinnedLoader.integrity` to its hash. The URL must be `https` on the default collector origin or your own `apiUrl` origin. |

`init()` does not pass `consentMode` to the loader. To declare a mode, put `data-consent-mode` on the tag or call `createClient` directly.

### 5. Set the log level

The loader writes nothing to the console by default. Four sources can change that. The highest one that holds a valid value wins:

1. The `data-log-level` attribute on the script tag.
2. The `logLevel` option of `createClient()` or `init()`, or `NoxticaCollector.setLogLevel(level)`.
3. The domain setting. In Backoffice open Domains, open the domain, then Configuration → **Client log level** → **Console log level**. The choices are SDK default, Silent, Error, Warn, Info and Debug. The value arrives with each session token, so a change applies from the next token.
4. The SDK default: silent, unless `data-debug`, the `debug` option or `window.NOXTICA_DEBUG = true` turns on `debug`.

`silent` means no console output from any Noxtica code path. Read the effective level with `window.NoxticaCollector.getLogLevel()`.

A `data-log-level` attribute applies before the loader reads the other attributes, so it also reveals the warnings from step 2, such as a rejected `data-api-url`. The domain setting arrives later, with the token.

## Verify it works

Run these in the browser console on a page that carries the tag:

```javascript
typeof window.noxticaClient;            // 'object' when data-auto-init bound the tag
window.noxticaClient.siteKey;           // your Site Key
window.noxticaClient.apiUrl;            // the collector origin in use
window.noxticaClient.ingestUrl;         // the telemetry origin in use
window.NoxticaCollector.VERSION;        // the loader version, for example '3.8.1'
window.noxtica.v;                       // the same version, published for the duplicate-tag guard
window.NoxticaCollector.getLogLevel();  // the effective log level
```

In DevTools → Network you see `POST /client/token` on the collector host with status `200`. After consent, when the extensions run, and with `data-ingest-url` left at `auto` on the default collector, telemetry requests go to `ingest.noxtica.com`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `window.noxticaClient` is undefined and no `noxtica:*` event fires | The tag lacks `data-auto-init` or `data-site-key`, or the `src` file name contains neither `noxtica-collector` nor `/noxtica.js` | Add the attributes, or keep the original file name when you copy or proxy the script. |
| `data-api-url` has no effect | The value is not `https` and not on `localhost` or `127.0.0.1`, or it is not a valid URL | Use an `https` URL. The warning appears at log level `warn` or higher. |
| Telemetry still goes to the collector host | `data-ingest-url` equals the collector origin, or `data-api-url` points at a host other than the default collector | Set `data-ingest-url` to the telemetry origin you want. |
| Changing an attribute in the console changes nothing | The loader read the attributes when the tag initialised | Reload the page, or create a client from code. |
| `getConsent().mode` differs from `data-consent-mode` | The mode saved for the domain wins once the token arrives | See [Consent modes](https://noxtica.com/docs/sdk/consent/). |
| `NX001: already loaded` in the console | A second core or combined tag is on the page, for example one pasted by hand and one from a tag manager | Remove the extra tag. The initial one keeps running. |
| `NoxticaCollector: siteKey is required` | `createClient` found no Site Key | Pass `siteKey`, or keep `data-site-key` on a collector tag. |
| `403` with `Origin mismatch` on `/client/token` | The page origin is not the origin registered for the Site Key | Use the key of the exact origin the page runs on. |

## Related

- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): install, pinned tags, CSP and the check list.
- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/): the methods and events these attributes feed.
- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): what `data-consent-mode` and `data-extensions` do at run time.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/): a symptom table across the whole SDK.
- [SDK Changelog](https://noxtica.com/docs/changelog/): which release added or changed each setting.