@customerio/cdp-analytics-browser

@customerio/cdp-analytics-browser is the official client-side SDK for sending analytics data to Customer.io’s Data Pipelines (CDP) product from web browsers. It is a Customer.io-maintained fork of Segment’s analytics-next browser library, preserving the same plugin/middleware-based event pipeline while retargeting delivery at Customer.io’s ingestion endpoints and adding Customer.io-specific batching and dispatch logic.

The library exposes a small public surface — identify, track, page, group, and alias — while internally routing every call through a queue of pluggable destinations, middleware, and enrichment steps. This lets consumers extend or override event handling (e.g. injecting classic Segment integrations, custom middleware, or remote-loaded plugins) without touching the call sites in application code.

It ships as part of a monorepo alongside @customerio/cdp-analytics-core (shared queue/plugin primitives) and @customerio/cdp-analytics-node, and is built for both a UMD/CDN snippet-loader form and an ESM/CJS package form for bundler-based installs.

What You Get

• A small, stable public API (identify, track, page, group, alias) for instrumenting web apps
• A pluggable event pipeline (destinations, middleware, enrichment plugins) inherited from Segment’s analytics-next architecture
• Built-in offline/retry handling via a persisted priority queue backed by browser storage
• Support for classic Segment integrations via an ajs-destination compatibility plugin
• A CDN-loadable UMD snippet build in addition to the ESM/CJS package for bundler installs
• EU data-center support via a configurable cdnURL for regional Customer.io endpoints

Common Use Cases

• Instrumenting a marketing site or web app - a frontend team drops in the snippet loader or npm package to start sending identify/track/page calls to Customer.io CDP with minimal setup
• Migrating from Segment’s analytics.js - a team already using Segment’s browser SDK swaps in this drop-in-compatible fork to route the same event calls to Customer.io instead
• Extending event delivery with custom middleware - a team injects a middleware function to redact PII, enrich payloads, or conditionally suppress events before they reach the destination queue
• Supporting EU-hosted workspaces - a Customer.io customer in the EU data center configures the cdnURL option so browser events route to the correct regional ingestion endpoint
• Loading legacy Segment integrations - a team with existing classic Segment integrations (e.g. Amplitude) wires them in through the classicIntegrations option for continued compatibility

Under The Hood

Architecture The SDK centers on an Analytics class (packages/browser/src/core/analytics/index.ts) that resolves loosely-typed call arguments via an arguments-resolver module, wraps them in an immutable Context object, and pushes them onto an EventQueue (core/queue/event-queue.ts) — a browser-specific subclass of CoreEventQueue imported from the sibling @customerio/cdp-analytics-core package. The queue is backed by a PersistedPriorityQueue (lib/priority-queue/persisted) that survives page reloads and retries failed deliveries up to a configurable attempt count, giving the system resilient at-least-once delivery semantics without a server-side component. Destinations, middleware, and enrichment steps are all implemented as Plugin objects registered against the queue, so the core dispatch loop stays generic while behavior (legacy ajs-destination integrations, remote-loader plugins, routing-middleware, schema-filter) is added by composing plugins rather than branching inside Analytics itself — the same extension pattern Segment’s analytics-next popularized, retained here after the Customer.io fork.

Tech Stack The package is TypeScript throughout, built with tsc into separate ESM (dist/pkg), CJS (dist/cjs), and a webpack-bundled UMD build (dist/umd) for CDN/snippet loading, all orchestrated via Turborepo and Yarn 3 workspaces across the monorepo. Runtime dependencies are deliberately narrow and vendored for size: @lukeed/uuid for ID generation, dset for nested property assignment, js-cookie and a UniversalStorage abstraction for persistence, spark-md5 for hashing, and unfetch/node-fetch for fetch parity across environments. @segment/facade and @segment/analytics.js-integration* packages are retained as devDependencies to support the classic-integrations compatibility layer. Bundle size is actively enforced via size-limit (28KB cap on the UMD build), and Playwright drives cross-browser installation/integration tests.

Code Quality The package has substantial Jest test coverage (60+ *.test.ts files spread across core/, lib/, and plugins/), including dedicated suites for the priority queue, arguments resolver, and each destination/middleware plugin. TypeScript strict-ish typing is used throughout the public API surface (AnalyticsSettings, InitOptions, typed event params), though comment density in core files is modest — logic is expected to be self-documenting via naming rather than narrated inline. ESLint and tsc --noEmit both run as part of yarn lint, and GitHub Actions workflows (test.yml, release.yml, pre-release.yml) gate merges and automate npm/CDN releases via Changesets.

What Makes It Unique Rather than building a Customer.io-specific analytics client from scratch, this package is a maintained fork of Segment’s open-source analytics-next, preserving its plugin/middleware extensibility model (a well-proven design for event pipelines) while swapping the destination layer for Customer.io’s CDP ingestion API and adding Customer.io-specific batched dispatch. This gives existing Segment users a low-friction migration path — the same call signatures and plugin extension points — while giving Customer.io a pipeline architecture that already handles offline queuing, retries, and legacy-integration compatibility rather than reinventing them.