Skip to main content

Usercentrics

Installation​

npm install @walkeros/web-source-cmp-usercentrics

Usage​

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',
          },
        },
      },
    },
  },
});

Settings​

SettingTypeDefaultDescription
eventNamestring'ucEvent'Window event name configured in Usercentrics admin
categoryMapRecord<string, string>{}Maps Usercentrics categories to walkerOS consent groups
explicitOnlybooleantrueOnly process explicit consent (user made a choice)

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,
        },
      },
    },
  },
});

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.

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 Professional Support?
Need professional support with your walkerOS implementation? Check out our services.