Advanced Configuration

Runtime configuration guide for batching, data-layer modules, reverse mapping, and debug controls.

Audience: Integration engineers who need deterministic behavior tuning beyond default setup.

Critical: Configuration is fetched from runtime endpoints; avoid undocumented fields or assumed mappings.

Public API Data Layer Guide Consent Management

Who This Page Is For

Use this page when default behavior is not enough and you need to control buffering, flush cadence, consent gating, module enablement, or reverse mapping from an external data layer.

Quick Start (2-5 Minutes)

Read runtime config source

Client reads config primarily from `/config` and falls back to `/tracking-config`.

GET /api/v1/public/sites/:siteKey/config
GET /api/v1/public/sites/:siteKey/tracking-config

Validate batch controls

Check batch size, flush interval, retry and persistence fields.

{ "batchingEnabled": false, "batchSize": 50, "flushInterval": 30, "offlinePersistence": true }

Validate data-layer config

Ensure variableName, tracking modules, consent options, and buffer controls are set as expected.

{ "dataLayerConfig": { "enabled": true, "variableName": "selwiseLayer", "bufferSize": 10, "flushInterval": 1000 } }

Add reverse mapping only when needed

Map external event names to canonical Selwise event names.

reverseEventMapping: { begin_checkout: 'checkout_begin', purchase: 'purchase' }

Required Fields / Minimum Payload

Config block	Required fields	Default
Tracker batch	`batchingEnabled`, `batchSize`, `flushInterval`	`false`, `50`, `30` (sec)
Data layer core	`enabled`, `autoPageTracking`	`true`, `true`
Data layer buffering	`bufferSize`, `flushInterval`	`10`, `1000` (ms)
Reverse listener	`reverseEventMapping`	not set
External listener target	`externalDataLayerName`	`dataLayer`
Debug	`debugMode`	`false`

DataLayerConfig runtime fields:

interface DataLayerConfig {
  enabled: boolean;
  variableName?: string; // default: 'selwiseLayer'
  pageDetection?: 'auto' | 'manual' | 'patterns';
  autoPageTracking: boolean;
  cartAbandonmentTimeout: number; // minutes
  pageTypePatterns: Record<string, RegExp>;
  debugMode: boolean;
  cookieConsent?: {
    enabled: boolean;
    variableName: string;
    waitForConsent: boolean;
    defaultConsent: boolean;
    timeoutMs?: number;
    granular?: boolean;
    requiredCategories?: Array<'necessary' | 'analytics' | 'marketing' | 'preferences'>;
    consentChangeCallback?: string;
    storageKey?: string;
  };
  trackingModules?: {
    page?: { enabled: boolean };
    product?: { enabled: boolean };
    basket?: { enabled: boolean };
    checkout?: { enabled: boolean };
    user?: { enabled: boolean };
    search?: { enabled: boolean };
  };
  bufferSize?: number;
  flushInterval?: number;
  reverseEventMapping?: Record<string, string>;
  externalDataLayerName?: string;
}

Event or Endpoint Decision Matrix

Goal	Choose	Why
Fast initial load with one request	`GET /public/sites/:siteKey/config`	Returns campaigns/widgets/recommendations/tracking in one payload.
Fallback tracking config only	`GET /public/sites/:siteKey/tracking-config`	Used when batch config endpoint is unavailable.
Listen to existing GTM dataLayer	`reverseEventMapping` + `externalDataLayerName`	Maps external names to canonical Selwise event names.
Control queue memory/latency	`bufferSize` + `flushInterval` (ms)	Balances real-time visibility and network overhead.
Diagnose integration behavior	`debugMode` + `localStorage.selwise_debug=true`	Enables integration-level logging for troubleshooting.

Reverse Event Mapping

Only event-name mapping is supported.

Supported: reverseEventMapping (externalName -> canonicalSelwiseName)
Supported: externalDataLayerName
Not supported: fieldMapping path-to-path transformation contract

Reverse mapping example

{
reverseEventMapping: {
  begin_checkout: 'checkout_begin',
  checkout_progress: 'checkout_progress',
  purchase: 'purchase',
  product_viewed: 'product_view'
},
externalDataLayerName: 'dataLayer'
}

Common Runtime Response Shape

Tracking config response (typical shape)

{
"batchingEnabled": false,
"batchSize": 50,
"flushInterval": 30,
"offlinePersistence": true,
"sendBeaconOnUnload": true,
"maxRetries": 3,
"maxQueueSize": 100,
"maxStorageEvents": 50,
"debugMode": false,
"dataLayerConfig": {
  "enabled": true,
  "variableName": "selwiseLayer",
  "pageDetection": "auto",
  "autoPageTracking": true,
  "cartAbandonmentTimeout": 30,
  "pageTypePatterns": {},
  "trackingModules": {
    "page": { "enabled": true },
    "product": { "enabled": true },
    "basket": { "enabled": true },
    "checkout": { "enabled": false },
    "user": { "enabled": false },
    "search": { "enabled": false }
  },
  "bufferSize": 10,
  "flushInterval": 1000
}
}

Common Errors and Fixes

External dataLayer events not appearing in Selwise

Cause: Missing or wrong `reverseEventMapping` event-name keys.

Fix: Map exact external event name to canonical Selwise name.

High event latency

Cause: Flush interval too high or buffering settings too aggressive.

Fix: Lower `dataLayerConfig.flushInterval` and verify batching policy.

Unexpected event drops under consent

Cause: Consent config active with unmet categories/timeouts.

Fix: Check `cookieConsent` fields and runtime consent state.

No debug logs during tests

Cause: Debug not enabled in runtime config/local storage.

Fix: Set `debugMode=true` and `localStorage.setItem("selwise_debug", "true")`.

Production Checklist

Primary config endpoint (`/config`) responds successfully.Required
Fallback endpoint (`/tracking-config`) tested once.Required
No unsupported `fieldMapping` assumptions in integration docs/code.Required
reverseEventMapping outputs canonical event names only.Required
Buffer and flush values validated against expected traffic volume.Required
Debug mode disabled for production unless incident diagnostics require it.Required