Beslist Tracking SDK

A modular tracking SDK for Beslist.nl affiliate tracking. Handles event tracking, identity management, consent, and reliable event delivery with offline queuing and fallback transport mechanisms.

Quick start

import { resolveConfiguration } from './configuration';
import { BeslistTracker } from './tracker';
import { stripUnknownQueryParams } from './events';

const tracker = new BeslistTracker(
    resolveConfiguration('shop-123'),
    { sanitizers: [stripUnknownQueryParams] },
);

// Initialize session (sends a session_start event if a new session is detected)
await tracker.initializeSession();

// Initialize session with ecommerce data (e.g. on a product-detail page view).
// The ecommerce shape is free-form — the backend defines it.
await tracker.initializeSession({
    items: [
        {
            id: 'SKU-123',
            name: 'Wireless Headphones',
            price: 49.95,
            brand: 'Acme',
            categories: ['Audio', 'Headphones'],
            ean: '0123456789012',
            stock: 42,
        },
    ],
});

// Track a conversion
await tracker.trackConversion({
    value: 49.95,
    transactionID: 'TX-001',
    includingVAT: true,
});

// Cookieless ping (consent-independent) — requires `cookielessPingEnabled` in config.
// Fires regardless of consent; reports the consent state for diagnostics only.
const consentAwareTracker = new BeslistTracker(
    resolveConfiguration('shop-123', { cookielessPingEnabled: true }),
);
await consentAwareTracker.sendConversionPing(
    { value: 49.95, transactionID: 'TX-001', includingVAT: true },
    { functional: true, analytics: true, marketing: false },
);
await consentAwareTracker.sendSessionStartPing({ analytics: true, marketing: false });

// Clean up when done
tracker.destroy();

Architecture

graph TD
    BeslistTracker["`**TRACKER**
    BeslistTracker`"]

    BeslistTracker --> Configuration["`**CONFIGURATION**
    TrackingOptions`"]
    BeslistTracker --> Consent["`**CONSENT**
    ConsentProvider`"]
    BeslistTracker --> Events["`**EVENTS** 
    BeslistEvent`"]
    BeslistTracker --> Identity["`**IDENTITY**
    IdentityManager`"]
    BeslistTracker --> Transport["`**TRANSPORT**
    TransportClient`"]
    BeslistTracker --> ClientStorage["`**CLIENT-STORAGE**
    EventQueueManager`"]
    BeslistTracker --> Functions["`**FUNCTIONS**
    Utilities`"]
    BeslistTracker --> Debug["`**DEBUG**
    Logger`"]

    Identity --> ClientStorage
    ClientStorage --> Cookies["`**COOKIES**
    RawCookieStorage`"]
    Functions --> Constants["`**CONSTANTS**`"]
    Events --> Constants
    Configuration --> Constants

    style BeslistTracker fill:#4a90d9,color:#fff

Layers

| Layer | Description | |-------|-------------| | cookies | Low-level cookie read/write and helpers | | debug | Conditional scoped logging | | constants | Shared constants (cookie names, endpoints, parameters) | | functions | Standalone utility functions (ID generation, session start detection) | | client-storage | Storage abstraction, typed repositories, and event queue | | transport | HTTP transport with pluggable adapters and serializers | | identity | User and session identity management via cookies | | events | Event definitions, serialization, and sanitization | | consent | Consent management abstraction | | configuration | SDK configuration, validation, and defaults | | tracker | Main facade that orchestrates all layers |

Layers are listed bottom-up: foundational layers first, higher-level layers last. Click any layer to see its README with detailed documentation.