You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Create @dotcms/events: one SDK for analytics and experiments #37683
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.
@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.
Description
Decision: replace
@dotcms/analyticsand@dotcms/experimentswith a new SDK,@dotcms/events, that does both. OnedotEventsobject, set up by oneinitcall, 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:
context.experiments, and a pageview on an experiment page waits for the variant decision. Two SDKs meant two instances coordinating that across packages.init, one config, and the samedotEventsimport everywhere, instead of two SDKs with their own providers and hooks.ca.min.js, instead of@dotcms/analytics'sca.min.jsplus the experiments script dotCMS injects today.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 ofca/html/analytics_head.htmland decides experiments from the contentlet wrappers dotCMS prints.@dotcms/uve,@dotcms/reactand the other SDKs do not change.Acceptance Criteria
@dotcms/eventsships with the SDK release, with its three entries andca.min.js.@dotcms/eventsalone.ca.min.jsalone, 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/analyticsand@dotcms/experimentsare marked deprecated, with a migration note:window.dotAnalyticsbecomeswindow.dotEvents, andtrackhas no replacement, since dotCMS rejects custom events.Priority
High
Additional Context
@dotcms/eventsdraft PR).libs/sdk/events/README.mdandCLAUDE.mddocument the architecture and the decisions behind it.ca.min.jsthe only analytics and experiments script on traditional pages).