Skip to content

Create @dotcms/events: one SDK for analytics and experiments #37683

Description

@erickgonzalez

Description

Decision: replace @dotcms/analytics and @dotcms/experiments with a new SDK, @dotcms/events, that does both. One dotEvents object, set up by one init call, runs a single Analytics.js instance for pageviews, conversions, content impressions and content clicks, and runs experiments inside it.

Why one SDK instead of two:

  • Experiments depend on analytics: every event carries the visitor's context.experiments, and a pageview on an experiment page waits for the variant decision. Two SDKs meant two instances coordinating that across packages.
  • Developers configure one thing: one init, one config, and the same dotEvents import everywhere, instead of two SDKs with their own providers and hooks.
  • Traditional (VTL) pages get one script, ca.min.js, instead of @dotcms/analytics's ca.min.js plus the experiments script dotCMS injects today.
  • It is greenfield: it sends only what dotCMS accepts today, so there is no custom-event API, and conversions carry a name only.

What it ships:

  • @dotcms/events: dotEvents (init, conversion, pageView) and the types its API uses.
  • @dotcms/events/markup: experimentMarkup, what a server-rendered page prints so its experiment runs.
  • @dotcms/events/react: DotCMSExperiment, which prints that markup in React.
  • ca.min.js: the IIFE dotCMS injects into traditional pages. It reads the attributes of ca/html/analytics_head.html and decides experiments from the contentlet wrappers dotCMS prints.

@dotcms/uve, @dotcms/react and the other SDKs do not change.

Acceptance Criteria

  • @dotcms/events ships with the SDK release, with its three entries and ca.min.js.
  • Headless apps send pageviews, conversions, content impressions and clicks, and run experiments, through @dotcms/events alone.
  • Traditional pages run analytics and experiments from ca.min.js alone, once Run @dotcms/events on traditional pages as a new opt-in script, /ext/events/events.min.js #37798 (backend changes that make it the only script) ships.
  • @dotcms/analytics and @dotcms/experiments are marked deprecated, with a migration note: window.dotAnalytics becomes window.dotEvents, and track has no replacement, since dotCMS rejects custom events.

Priority

High

Additional Context

Activity

  1. moved this from New to Current Sprint Backlog in dotCMS - Product Planningon Sep 22, 2026
  2. moved this from Current Sprint Backlog to Spec In Progress in dotCMS - Product Planningon Sep 23, 2026
  3. self-assigned this
    on Sep 23, 2026
  4. changed the title [-][Placeholder] SDK Changes[/-] [+]Create @dotcms/events: one SDK for analytics and experiments[/+] on Sep 29, 2026
  5. removed their assignment
    on Oct 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions