Skip to main content

Usercentrics

Integrates Usercentrics consent management with walkerOS by listening for a configured window event and mapping category or service consent state to walkerOS consent groups.

Installation​

npm install @walkeros/web-source-cmp-usercentrics
import { startFlow } from '@walkeros/collector';
import { sourceUsercentrics } from '@walkeros/web-source-cmp-usercentrics';

await startFlow({
  sources: {
    consent: {
      code: sourceUsercentrics,
      config: {
        settings: {
          eventName: 'ucEvent', // Must match your Usercentrics admin config
          categoryMap: {
            essential: 'functional',
            functional: 'functional',
            marketing: 'marketing',
          },
        },
      },
    },
  },
});

Configuration​

This source uses the standard source config wrapper (consent, data, env, id, ...). For the shared fields see source configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
eventNamestringWindow event name to listen for, configured in the Usercentrics admin (Implementation > Data Layer & Events). Use 'UC_SDK_EVENT' for the built-in Browser SDK event. Default: 'ucEvent'.
categoryMapRecord<string, string>Map the CMP's consent categories (keys) to walkerOS consent groups (values).
explicitOnlybooleanOnly process consent_status events where type is 'explicit'. Ignores implicit/default page-load events. Default: true.

Mapping​

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Examples

category map override

Event
Mapping
Out

custom event name

Event
Mapping
Out

full consent

Event
Out

minimal consent

Event
Out

How it works​

  1. Event listener: Registers a listener for the configured window event (default: ucEvent).

  2. Group vs. service detection: Checks if ucCategory values are all booleans:

    • Group-level: Uses ucCategory as consent state (maps categories via categoryMap)
    • Service-level: Extracts individual service booleans from event.detail (normalized to lowercase_underscores) and applies categoryMap to boolean ucCategory entries

  3. Explicit filtering: By default, only processes events where type === 'explicit' (user actively made a choice). Set explicitOnly: false to also process implicit/default consent.

  4. Consent command: Calls elb('walker consent', state) with the mapped consent state.

Usercentrics setup​

Configure a Window Event in your Usercentrics admin: Implementation > Data Layer & Events > Window Event Name (e.g., ucEvent).

Usercentrics window event implementation

Alternatively, set eventName: 'UC_SDK_EVENT' to use the built-in Browser SDK event (no admin configuration required).

Custom mapping example​

await startFlow({
  sources: {
    consent: {
      code: sourceUsercentrics,
      config: {
        settings: {
          eventName: 'ucEvent',
          categoryMap: {
            essential: 'functional',
            functional: 'functional',
            marketing: 'marketing',
          },
          explicitOnly: true,
        },
      },
    },
  },
});

Timing considerations​

The source should be initialized before the Usercentrics script loads to avoid missing the initial consent event. When using explicitOnly: true (default), this is not a concern since the implicit init event is filtered anyway. For explicitOnly: false, ensure the consent source has no require constraints so it initializes immediately.

Reference​

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)