Skip to main content

Web analytics

Databuddy

The c15t databuddy helper waits for measurement consent before it loads databuddy.js. Before the visitor allows measurement, the page sends no request to Databuddy and Databuddy stores nothing. If the visitor withdraws consent, the helper disables the Databuddy tracker and stops session replay, and c15t reloads the page.

Configure Databuddy

Copy the client ID from your Databuddy project. The helper passes it to the script as data-client-id. Remove any existing Databuddy or replay.js script tag, any <Databuddy /> component from @databuddy/sdk, and any code that sets window.databuddyConfig. The helper seeds that global only when it is absent, so an existing value overrides it.

npm install @c15t/integrations
src/consent-scripts.ts
import { databuddy } from '@c15t/integrations/databuddy';

export const scripts = [
	databuddy({ clientId: 'YOUR_CLIENT_ID', features: { interactions: false } }),
];

Register the scripts

Complete your framework quickstart first. Keep its Inth endpoint, policy, styles and consent UI. Remove the vendor's original script, SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in src/consent-scripts.ts. If your framework quickstart already has a scripts array, such as the one in c15t.config.ts in the Next.js guide, add the helper to that array instead of creating a second file. The scripts export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration point for your framework below. These are edits to that provider, not a second provider.

Add the configuration to scripts in c15t.config.ts, next to next.config.ts:

import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });

Keep the rest of your config, such as mode and routePrefix, in the same call. ConsentRoot reads the config in the browser, so the layout keeps passing only state. App Router, Pages Router and static export all read the same file. See Next.js scripts and embeds.

Options

OptionDefaultBehavior
clientIdRequiredSet as data-client-id. The helper trims it. Empty or whitespace-only values log an error and the script does not load.
loadMode'after-consent'When the script loads. See loading and revocation.
features.interactionsUnset, Databuddy turns it onSets data-track-interactions.
features.webVitalsUnset, Databuddy turns it offSets data-track-web-vitals.
features.errorsUnset, Databuddy turns it offSets data-track-errors.
features.outgoingLinksUnset, Databuddy turns it offSets data-track-outgoing-links.
replayfalsetrue or an object loads replay.js while measurement is allowed. See record sessions.
replay.maskTextUnset, Databuddy masks textSets data-mask-text on replay.js. false records page text.
replay.recordIframesUnset, Databuddy turns it offSets data-record-iframes on replay.js.
replay.scriptUrlhttps://cdn.databuddy.cc/replay.jsReplay script URL override. A blank value falls back to the default.
configWhenGranted{ apiUrl, clientId, disabled: false }Object set as window.databuddyConfig before the script loads with measurement allowed, and on each grant. c15t sets its disabled key from consent.
configWhenDenied{ apiUrl, clientId, disabled: true }With loadMode: 'always' only. Object set as window.databuddyConfig before the script loads without measurement permission, and on each refusal. c15t sets its disabled key from consent.
apiUrlhttps://basket.databuddy.ccCollection endpoint, set as data-api-url.
scriptUrlhttps://cdn.databuddy.cc/databuddy.jsLoader URL override. A blank value falls back to the default.

Turn off features you do not use

Databuddy collects some data unless the site turns it off. Set a features switch to false to stop that collection, or to true to turn on a feature Databuddy leaves off:

databuddy({
	clientId: 'YOUR_CLIENT_ID',
	features: {
		interactions: false,
		webVitals: false,
		errors: false,
		outgoingLinks: false,
	},
});
SwitchDatabuddy defaultWhat Databuddy collects
interactionsOnRage clicks, dead clicks and abandoned forms
webVitalsOffFCP, LCP, INP, CLS, TTFB and FPS
errorsOffJavaScript errors, with message and stack
outgoingLinksOffClicks on links to other sites

Each switch sets a data-track-* attribute on the script. An unset switch sets no attribute, so Databuddy keeps its own default. Databuddy reads data-* attributes after window.databuddyConfig, so a switch wins over the same key in configWhenGranted or configWhenDenied.

Loading and revocation

loadModeWhen databuddy.js loadsBefore the visitor allows measurement
'after-consent'Only while measurement is allowedNo request to Databuddy and no storage
'always'On every page, before consentThe script loads and stores a visitor ID while disabled stops it sending

On revocation, the helper sets window.databuddy.options.disabled to true, which stops the main tracker sending. It also sets disabled: true in window.databuddyConfig, or replaces the object with configWhenDenied in 'always' mode. A databuddy.js download that finishes after the refusal then starts disabled. With replay on, the helper also stops the recorder. c15t then reloads the page, which is the default reloadOnConsentRevoked behavior. On a later grant, c15t sets both back to false, and window.databuddyConfig to configWhenGranted.

With loadMode: 'always', databuddy.js runs before the visitor chooses. It stores its visitor ID in localStorage even while disabled is true. Databuddy's own consent guidance is to delay loading until consent where prior consent is required. Use 'always' only where your policy allows that.

Record sessions

Databuddy records sessions with a separate script, replay.js. Set replay to have the helper load it:

databuddy({ clientId: 'YOUR_CLIENT_ID', replay: true });

replay: true keeps Databuddy's replay defaults, which mask page text and typed input. The helper adds replay.js only while measurement is allowed, including with loadMode: 'always', and passes it the same clientId and apiUrl as databuddy.js. replay.js does not read Databuddy's disabled flag, so the helper calls window.databuddyReplay.stop() and removes the script on revocation. It does the same when you turn replay off, remove the helper or dispose the script loader. Recording stops without waiting for the page reload. A later grant loads replay.js again.

replay: { maskText: false } records page text; typed input stays masked. Use it only when your pages show no personal data, such as names, email addresses or order details. Recordings would otherwise include that data. To change masking for one element, add an attribute to it in your markup:

  • data-replay-unmask records the text of an element that is safe to show.
  • data-replay-block leaves the element out. The recording shows an empty box of the same size.

recordIframes: true records your own embedded pages into the parent page's recording. Set it on the framed page too. See Databuddy's session replay guide for its limits and the dashboard setting that turns replay off.

Do not also add replay.js to the page as a plain <script> tag. Outside c15t, it starts recording on the visitor's first click, scroll or key press, and uploads that recording even if the visitor has not chosen.

Verify Databuddy

  1. In a private window with an opt-in policy, load the page. DevTools Network shows no request to cdn.databuddy.cc or basket.databuddy.cc, and Application shows no did key in localStorage.
  2. Click Reject, then reload. There are still no Databuddy requests.
  3. Open Privacy settings and allow measurement. Without a reload, databuddy.js loads from cdn.databuddy.cc with your data-client-id, and requests reach your apiUrl. With replay on, replay.js loads too. Move the pointer or scroll, and a POST to /replay follows within a few seconds.
  4. Turn measurement off again and save. c15t reloads the page, and the new page sends no request to cdn.databuddy.cc or basket.databuddy.cc.

See the consent verification guide for navigation and hosting checks.