Analytics

Marketing wants to know which landing page the Black Friday banner sends people to, without adding tracking cookies or a third-party tag manager.

Deco CMS includes small, open-source web analytics compatible with One Dollar Stats. It counts page views without cookies, and its settings are content: the analytics section of your site's CMS settings, so editors can change them in the site editor. This page shows how to add it, where page views go, how to send your own events and how to turn it off.

Analytics has nothing to do with telemetry: telemetry is errors, metrics and traces from your servers, while analytics is page views from the browser. They only share the settings block, each in its own section.

Add analytics to your site

1. Render the script

Read the settings with cms.settings() in your root layout and pass the analytics section to AnalyticsScript, from @decocms/blocks/analytics, so every page gets it:

import { AnalyticsScript } from "@decocms/blocks/analytics";
import { cms } from "../cms";
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const { analytics } = await cms.settings();   // the release's settings, defaults filled in
 
  return (
    <html lang="en">
      <body>
        {children}
        <AnalyticsScript {...analytics} />
      </body>
    </html>
  );
}

That's all it takes: with no settings saved, the defaults apply, and page views go to the hosted Deco CMS collector (which counts them for connected sites; otherwise, set collector below). It works the same on every framework, since cms.settings() returns plain values. In the browser, the script sends a page view on every navigation: the path without its query string, the referrer and the hostname.

2. Choose where page views go (optional)

To send page views to your own collector, set collector in the analytics section, in the site editor's Settings or by hand:

{
  "__resolveType": "cms-settings",
  "analytics": { "collector": "https://stats.example.com/events" }
}

The settings come from the release your servers serve, never from a draft: a change ships like any other content, and previewing a draft doesn't change where page views go.

Settings

The analytics section's fields, which are also AnalyticsScript's props:

There's no site ID: like One Dollar Stats, the collector tells sites apart by the page's hostname. The exact type is in the API reference.

Send your own events

Call track from @decocms/blocks/analytics, with an event name and optional properties:

import { track } from "@decocms/blocks/analytics";
 
<button onClick={() => { addToCart(sku); track("add_to_cart", { sku }); }}>Add to cart</button>

track sends through the script AnalyticsScript renders. On a page without it, track does nothing.

Ecommerce events, such as a product view or a purchase, belong to your platform template: it calls track next to its own tag manager push, so Deco CMS itself knows nothing about carts or orders.

Turn it off

Set enabled to false in the analytics section, in the site editor or by hand:

{
  "__resolveType": "cms-settings",
  "analytics": { "enabled": false }
}

It's a content edit, so it ships like any other, and switching it back on is the same one-field commit. Like any field, the section can have variants, to switch analytics on only during a campaign, for example. cms.settings() picks the variant when your layout calls it, so its rules see the request the way your other matchers do.

One Dollar Stats

Page views use the wire format of the One Dollar Stats tracker, so the two halves mix and match:

• point collector at One Dollar Stats' own collector, or
• use their tracker script on your site and send to a collector that accepts the format.

The format isn't versioned, so Deco CMS tests against a pinned tracker version; the details are under the hood.

Privacy

• The tracker described here uses no cookies or browser storage. Its page-view payload contains a path, a referrer and a hostname; it does not generate a browser identifier.
• Collector behavior is separate from that payload. A server can also receive transport information such as an IP address and User-Agent. For example, One Dollar Stats documents session hashes using those values and an hourly timestamp. Compatibility with its event format does not establish the privacy practices of every collector, including Deco's hosted collector; check the collector you choose.
• Query strings are dropped, so search terms and tracking parameters stay out of your data. Keep personal data out of track properties.