<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Dmitrijs Gizdevans on Medium]]></title>
        <description><![CDATA[Stories by Dmitrijs Gizdevans on Medium]]></description>
        <link>https://medium.com/@dmitrijs.gizdevans?source=rss-2f006587f959------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*lDVCviXuHfQVeovFIvoJhQ.png</url>
            <title>Stories by Dmitrijs Gizdevans on Medium</title>
            <link>https://medium.com/@dmitrijs.gizdevans?source=rss-2f006587f959------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 10:28:20 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@dmitrijs.gizdevans/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[dataLayer Live View: a DevTools script for everyday tracking debugging]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/datalayer-live-view-a-devtools-script-for-everyday-tracking-debugging-b826442585d4?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/b826442585d4</guid>
            <category><![CDATA[debugging]]></category>
            <category><![CDATA[google-tag-manager]]></category>
            <category><![CDATA[devtools]]></category>
            <category><![CDATA[web-analytics]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Sat, 03 Oct 2026 06:11:50 GMT</pubDate>
            <atom:updated>2026-10-03T06:15:31.183Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/942/1*YPoK6k2BTK_0r40wpUKeRg.png" /></figure><p>➤ TL;DR: dataLayer Live View is a standalone JavaScript script for DevTools that intercepts dataLayer.push() and shows the event stream in the Console in real time. It labels entries by type (EVENT, gtm.*, GTAG, DATA), snapshots every push, shows what was already in the dataLayer before it started, and can trace where a push came from. No extension, no UI, no dependencies: paste it into the Console or run it as a Live Expression in Chrome or Edge.</p><p>When a product is constantly evolving, tracking is almost never something you can configure once and forget about.</p><p>New components appear, user journeys change, experiments are launched, pages and platforms migrate. Different parts of the product are owned by different functional teams, each making changes within its own area independently of the others.</p><p>For a tracking / web analytics team, this means a lot of manual testing.</p><p>You constantly need to check which events actually reach the dataLayer, in what order they appear, which parameters are passed, whether the payload changed after another release, and whether anything unexpected appeared.</p><p>When there are many changes, working with the dataLayer becomes an almost daily part of tracking QA.</p><h3>Why I prefer DevTools</h3><p>There are many excellent browser extensions for working with the dataLayer.</p><p>Some of them can show almost everything: the data layer, analytics payloads, network requests, ecommerce objects, consent state, and other implementation details.</p><p>But for everyday debugging, I still prefer using Developer Tools directly in the browser.</p><p>There are several reasons.</p><p>First, every extension is another installed browser component. It uses memory, has its own runtime, and adds another interface. If a few lines of JavaScript in the Console are enough for the task, I don’t always see a reason to keep a separate tool installed for it.</p><p>Second, I prefer working with data as close as possible to the form in which it actually appears in the browser. An extension can process, group, and present an event nicely. That’s useful, but during debugging I often want to see the actual dataLayer flow first and interpret it afterwards.</p><p>Third, there’s Incognito / InPrivate mode. Extensions are usually unavailable there unless explicitly allowed, while DevTools remains DevTools. Open the Console, run the script, and start working.</p><p>In that sense, I’m definitely a purist: if I can inspect what’s happening directly in the browser, that’s where I go first.</p><h3>But the regular Console quickly becomes awkward too</h3><p>The problem is that a modern dataLayer can be very noisy.</p><p>Even a single page load can generate a long stream of entries:</p><ul><li>tracking events</li><li>internal GTM events</li><li>gtag() commands</li><li>ecommerce resets such as { ecommerce: null }</li><li>configuration pushes</li><li>technical data</li><li>events triggered after the user starts interacting with the page</li></ul><p>You can, of course, keep calling dataLayer in the Console, expand the array, find the entry you need, compare objects, and repeat the process after the next interaction.</p><p>But when you need to validate many scenarios during the day, this workflow quickly gets in the way.</p><p>Over time, I ended up with separate console snippets: one for watching new pushes, another for highlighting events, another for finding the source of a call.</p><p>At some point, it made more sense to combine them into one tool.</p><p>That’s how <strong>dataLayer Live View</strong> came about.</p><h3>What is dataLayer Live View?</h3><p>dataLayer Live View is a standalone JavaScript script that runs directly in DevTools.</p><p>No browser extension, separate UI, or dependencies.</p><p>It intercepts dataLayer.push() and displays the event stream in the Console in real time.</p><p>The main goal is to make the dataLayer flow easier to read without turning debugging into a separate system.</p><p>The script currently distinguishes four main types of entries.</p><p>EVENT | &lt;name&gt; for pushes containing an event key.</p><p>EVENT | gtm.* for internal Google Tag Manager events such as gtm.js, gtm.dom, gtm.load, gtm.historyChange, and others.</p><p>GTAG for gtag() calls.</p><p>DATA for pushes without an event key, for example { ecommerce: null }.</p><p>Each type gets its own colored label, making it much easier to visually find the events you need in a long Console stream.</p><p>The script also shows container and tag IDs exposed through google_tag_manager, such as GTM-…, G-…, AW-…, and DC-….</p><h3>It also shows what happened before it started</h3><p>The script is often started after the page has already loaded, when the dataLayer already contains dozens of entries.</p><p>For that reason, dataLayer Live View first displays a collapsed group containing everything already present in the dataLayer, then switches to live mode and starts displaying new pushes.</p><p>This means you can start it on an already open page and immediately get some context about what happened earlier.</p><h3>A snapshot of every push</h3><p>There’s another Console behavior that can be annoying during debugging.</p><p>If an object is logged and then modified later, opening that log entry may show the object’s updated state rather than the state it had when console.log() was called.</p><p>For a tracking payload, this is especially problematic. You want to see exactly what was sent at a specific point in time.</p><p>That’s why dataLayer Live View creates a snapshot of every push as soon as it appears.</p><p>If the original object changes later, the Console entry remains in its previous state.</p><p>The script also handles circular references, DOM elements, and functions so that these values don’t break the output.</p><h3>Where did this push come from?</h3><p>Sometimes the problem isn’t the event itself, but not knowing what sent it.</p><p>For example, an event may appear twice, or its payload may unexpectedly change after another frontend update.</p><p>That’s what SHOW_SOURCE is for.</p><p>Enable it with:</p><pre>const SHOW_SOURCE = true;</pre><p>and each new push will include its call stack.</p><p>The number of stack trace lines can be changed with:</p><pre>const FRAMES = 3;</pre><p>In normal work, I keep source tracing disabled so the Console doesn’t turn into a stream of stack traces. I enable it only when I need to understand where a specific event came from.</p><h3>How to run it</h3><p>The simplest option is to open DevTools, go to Console, paste the contents of datalayer-live-view.js, and press Enter.</p><p>The script then starts displaying new dataLayer.push() calls.</p><p>After a page reload, it needs to be run again.</p><p>In Chrome and Edge, you can also use a Live Expression:</p><ol><li>Open Console.</li><li>Click <strong>Create live expression</strong>.</li><li>Paste the contents of the script.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SVng-XP3N8j8u-5ioTm9Mg.png" /></figure><p>The expression will then run again after navigation or reload.</p><p>If you want to keep previous Console output across reloads, you can also enable <strong>Preserve log</strong>.</p><h3>What can be configured</h3><p>There’s a small CONFIG block at the beginning of the script.</p><p>For example, if the implementation uses a custom data layer name:</p><pre>const DL_NAME = &#39;myDataLayer&#39;;</pre><p>To hide gtag() calls:</p><pre>const SHOW_GTAG = false;</pre><p>You can also change the number of stack frames and the colors used for different entry types.</p><h3>What it looks like</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*d4WyJYr19xABxFND6Y8hxA.png" /><figcaption>dataLayer Live View running as a Live Expression on Google Merch Shop in Incognito mode</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/945/1*2xN1Sm5xdW78fZQG6dRFXA.png" /><figcaption>Labeled dataLayer stream with an expanded view_item_list ecommerce payload</figcaption></figure><p>The result is still the regular DevTools Console. The event stream is simply much easier to read visually.</p><h3>Why I decided to publish it</h3><p>Here, minimalism isn’t a limitation. It’s the whole idea of the project.</p><p>I wanted a tool that:</p><ul><li>runs only when I need it</li><li>doesn’t require a browser extension</li><li>works directly in DevTools</li><li>shows data as close as possible to the original dataLayer flow</li><li>doesn’t add a separate UI</li><li>is easy to read and adapt to a specific project when needed</li></ul><p>A collection of working snippets eventually became a reusable script.</p><p>I cleaned it up, added a README, configuration, and changelog, and decided to make it public.</p><p>The project is called <strong>dataLayer Live View</strong>:</p><p><a href="https://github.com/dgizdevans/datalayer-live-view">https://github.com/dgizdevans/datalayer-live-view</a></p><p>The current version is 0.9.</p><p>For now, the scope is intentionally focused: live monitoring and debugging of the dataLayer. From here, the project can evolve around real problems that come up during tracking QA.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b826442585d4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Metrics as Code: a metric name is not a source of truth]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/metrics-as-code-a-metric-name-is-not-a-source-of-truth-90ba6fa829ff?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/90ba6fa829ff</guid>
            <category><![CDATA[ga4]]></category>
            <category><![CDATA[tracking]]></category>
            <category><![CDATA[web-analytics]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Wed, 02 Sep 2026 12:03:24 GMT</pubDate>
            <atom:updated>2026-09-02T12:08:46.500Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MoxASbKVjoRFS9SYivF8Ew.jpeg" /></figure><p><strong>TL;DR: </strong>→ DataLayer as Code defines what gets collected. It says nothing about what the numbers built on top of it mean.</p><p>→ A metric name is not a definition. Formula, grain, unit, dependencies and semantic source usually live in prose, spread across vendor docs, BI and internal wikis.</p><p>→ Metrics as Code stores each metric as a versioned YAML file: JSON Schema for structure, semantic checks for IDs, categories and dependencies, a dependency graph for references and cycles, and CI that fails when generated outputs drift from the source of truth.</p><p>→ The reference implementation covers 20 standard GA4 metrics, chosen because their semantics are published and independently verifiable. GA4 is the reference model here, not the proposed catalog.</p><p>→ The hard part was not the schema. It was turning published prose into strict definitions: contradictions between Google’s own pages, terms that differ by one letter, and the line between a formal dependency and an obvious inference.</p><p>→ {metric} means a formal link to another metric in the catalog. {term} means the term only appears in the published definition. The link is not added because it looks obvious.</p><p>→ Scope is deliberately narrow: semantics, not calculation. No connection to GA4, no queries, no verification of report values.</p><p>→ Two gaps remain: definition is not validated against implementation, and Metrics as Code and DataLayer as Code do not yet form a connected model.</p><h3>From DataLayer as Code to Metrics as Code</h3><p>DataLayer as Code formalizes what we collect: events, parameters, allowed values, and data structure. But even if this layer is well defined, the next question remains: what do the metrics built on top of this data actually mean?</p><p>I previously wrote about <a href="https://medium.com/@dmitrijs.gizdevans/before-asking-ai-for-insights-give-it-a-contract-a9a53948c06f">DataLayer as Code</a> and about a broader problem: <a href="https://medium.com/@dmitrijs.gizdevans/mcp-in-analytics-a-useful-interface-but-not-a-source-of-understanding-60602d95703d">MCP can give AI access to analytics systems, but access alone does not provide understanding</a>.</p><p>For an experienced analyst, engagementRate, purchaseRevenue, or activeUsers may be understandable with almost no additional explanation. But analytics is used by people with different levels of experience and with different frequency. For some, it is a daily working tool. Others need more context: what exactly is being calculated, at what level, which components make up the metric, and which definition it is based on.</p><p>For AI, this context matters even more. If the meaning of a metric exists only in documentation or is treated as “obvious”, the system has to reconstruct that meaning by itself.</p><p>This leads to another element of Analytics Context as Code: <strong>Metrics as Code</strong>, a machine-readable description of what each metric actually means.</p><h3>The problem: a metric name guarantees very little</h3><p>In real analytics systems, metric definitions rarely live in one place or in one format. Some are in vendor documentation, some in BI, some in internal wikis or Confluence, and some exist simply as shared knowledge inside the team.</p><p>As long as people work with these metrics, this can seem manageable. An experienced analyst knows what sits behind engagementRate or purchaseRevenue, where to check the definition, and which details need attention. But that knowledge is not part of the metric itself.</p><p>A name is not enough.</p><p>To interpret a metric correctly, you need to understand its definition, calculation method, grain, unit, dependencies, limitations, and semantic source.</p><p>The problem is that all of this is usually described in prose and distributed across different sources. Sometimes the definition is short and unambiguous. Sometimes the required information is spread across several documentation pages. Sometimes different pages from the same source describe the same rule slightly differently.</p><p>For a person, this means additional searching and interpretation. For AI, it means even more uncertainty. If the formula, dependencies, or source of a definition are not represented explicitly, they have to be inferred from text.</p><p>This is where prose documentation stops being enough. It works well for reading, but poorly as a strict contract that can be validated, compared across versions, and used without guessing.</p><h3>The idea behind Metrics as Code</h3><p>The idea is fairly simple: define a metric not as a line in documentation or a label in a report, but as a separate versioned, machine-readable object.</p><p>In the <a href="https://github.com/dgizdevans/metrics-as-code">Metrics as Code reference implementation</a>, each metric is stored in its own YAML file:</p><pre>metrics/<br>  acquisition/<br>  engagement/<br>  ecommerce/<br>  revenue/</pre><p>One metric, one file.</p><p>YAML is the single source of truth. A definition changes through Git, goes through review, and has a normal version history. You can see what changed, when, and why.</p><p>The structure of definitions is constrained by JSON Schema. Additional checks run on top of it, while metrics-index.json for machines and METRICS.md for people are generated automatically from the same YAML files.</p><p>CI checks both the definitions themselves and whether the generated outputs match the current source of truth.</p><p>As a result, a metric definition becomes a normal managed artifact. It can be validated, reviewed, versioned, and used by both people and machines.</p><h3>Why GA4</h3><p>For the reference implementation, I deliberately chose 20 standard GA4 metrics.</p><p>The reason is not GA4 itself. I needed a public model where the definitions already exist and are available in official documentation. This avoids inventing my own semantics and keeps the evaluation of the Metrics as Code approach separate from designing business metrics for a specific company.</p><p>The task was different: take already published definitions and see whether they can be translated consistently from prose documentation into a structured, machine-readable format.</p><p>This also makes the example verifiable. A reader can compare the definition of a metric with the original source linked to it. Every structured part of the definition should have a clear origin.</p><p>GA4 therefore acts as a public reference model. These 20 metrics are not a proposed standard catalog and do not define the boundaries of Metrics as Code itself.</p><p>In a real project, the same approach could be used for internal business metrics, metrics from another analytics vendor, or a mixed catalog covering several systems.</p><p>What matters is not which metrics are in the repository, but that their semantics stop existing only as prose and become formal, verifiable, and versioned definitions.</p><h3>What the contract looks like</h3><p>In the current reference implementation, a metric definition contains five required fields and seven optional ones.</p><p>Required:</p><pre>id:<br>name:<br>category:<br>description:<br>semantic_reference:</pre><p>Optional fields are included only when they are supported by the source and are actually needed to describe a particular metric:</p><pre>definition:<br>formula:<br>aggregation:<br>grain:<br>filters:<br>dependencies:<br>unit:</pre><p>For example, engagementRate can be described like this:</p><pre>id: engagementRate<br>name: Engagement rate<br>category: engagement<br>description: The percentage of engaged sessions.<br>semantic_reference: https://support.google.com/analytics/answer/12195621<br>formula:<br>  operator: divide<br>  operands:<br>    - metric: engagedSessions<br>    - metric: sessions<br>grain: session<br>unit: fraction</pre><p>The important part is that the formula is not stored as a string such as:</p><pre>engagedSessions / sessions</pre><p>Instead, it is represented as a structured object. This makes it possible to distinguish references to other metrics in the catalog from terms that exist only in the published definition.</p><p>An operand can have three forms.</p><p>A reference to another metric:</p><pre>- metric: engagedSessions</pre><p>A published term:</p><pre>- term: purchases</pre><p>Or a nested formula. For example, totalRevenue can be represented as a combination of several operations:</p><pre>formula:<br>  operator: subtract<br>  operands:<br>    - formula:<br>        operator: add<br>        operands:<br>          - term: purchases<br>          - term: in-app purchases<br>          - term: subscriptions<br>          - term: total ad revenue<br>    - term: refunds</pre><p>This distinction matters. {metric} represents a formal relationship with another metric in the catalog. {term} means only that the term appears in the published definition. If the source does not express a calculation through a specific named metric, that relationship is not added just because it seems obvious.</p><p>The contract therefore stores more than a textual description of a metric, capturing its identity, semantic source, formula, calculation level, and formal dependencies where those dependencies are actually supported by the source.</p><h3>What turned out to be harder than expected</h3><p>The most interesting part of the project started not with writing YAML or JSON Schema, but when published semantics had to be turned into strict definitions.</p><p>When a metric lives in documentation, small contradictions, wording differences, or missing details can easily stay unnoticed. Once the same information has to be expressed as a contract, every such case requires an explicit decision.</p><p>The first example is contradictions inside official documentation. For an engaged session, one Google page says “longer than 10 seconds”, while another says “10 seconds or longer”. In normal reading, the difference is easy to miss. In a formal definition, it creates a different boundary case at exactly 10 seconds.</p><p>I did not try to decide which wording better reflects GA4’s internal algorithm. Instead, the rule became simpler: each YAML file must be internally consistent with the source referenced in its semantic_reference.</p><p>The second case is similar terms. In Google’s documentation, Purchase revenue uses refund, while Total revenue uses refunds. It is tempting to normalize both into a single term, but that would introduce my interpretation into the contract instead of preserving the published semantics. So each term stays in the exact form used by its source.</p><p>Another difficult boundary was the difference between a formal dependency and an obvious inference.</p><p>For example, the description of sessionKeyEventRate refers to the total number of sessions. Technically, it would be very easy to represent the denominator as:</p><pre>- metric: sessions</pre><p>But that creates a formal reference to another metric in the catalog. If Google does not express the definition through the named Sessions metric, I do not treat that relationship as published.</p><p>So the rule is strict: metric is used only when the source actually expresses the calculation through a specific named metric. Otherwise, term is used, even when the relationship looks obvious to a human reader.</p><p>Sometimes the correct decision was to record nothing at all.</p><p>For example, eventsPerSession could have been given:</p><pre>unit: count</pre><p>But a value such as 3.7 events per session is not simply a count. If the available vocabulary cannot describe the semantics accurately, leaving the field absent is better than filling it with an approximation.</p><p>The same principle applied to the vocabulary itself. Values for grain were not designed in advance. user was added only when it became necessary for activeUsers, and item when itemsPurchased appeared.</p><p>Finally, some problems were visible only when definitions were compared with neighboring files.</p><p>For example, unit: fraction was initially added to one rate metric by analogy. The issue became visible only when another metric from the same class required a different decision.</p><p>This is an important effect of formalization: consistency becomes a property of the whole catalog, not just of an individual file. When definitions sit next to each other and follow the same rules, contradictions between them become easier to see than they are in normal documentation.</p><h3>Why this is a contract, not just a catalog</h3><p>At first glance, Metrics as Code may look like a metric catalog stored in YAML. But a catalog only stores definitions. A contract also defines the rules those definitions must follow.</p><p>The structure of each file is constrained by JSON Schema. Unknown fields are rejected through additionalProperties: false, so accidental or undefined structure does not pass validation.</p><p>Semantic checks run on top of the schema. They check unique IDs, allowed categories, resolvable dependencies, and correct references between metrics.</p><p>A dependency graph is also built. It includes both explicit dependencies and {metric} references inside formulas. This makes it possible to verify that all dependencies exist and that no cycles are introduced between metrics.</p><p>For example, if one metric references a metric that does not exist:</p><pre>formula:<br>  operator: divide<br>  operands:<br>    - metric: engagedSessions<br>    - metric: unknownMetric</pre><p>validation fails.</p><p>The same applies to cyclic dependencies. If metricA depends on metricB, and metricB directly or indirectly depends on metricA, the graph is invalid.</p><p>Documentation is not maintained separately either. metrics-index.json for machines and METRICS.md for people are generated from the same YAML files.</p><p>CI connects the whole process:</p><pre>npm ci<br>validate<br>generate<br>git diff --exit-code</pre><p>The final step checks that generated outputs match the current source of truth. If YAML changes while the derived files remain outdated, the build fails.</p><p>Changing a metric definition is therefore not just editing text, but a controlled change to an artifact that goes through schema validation, semantic validation, dependency graph checks, and CI, while documentation is generated from the same source.</p><p>That is what makes Metrics as Code a contract rather than a normal metric catalog.</p><h3>Scope and responsibility</h3><p>Metrics as Code describes metric semantics, but it does not calculate the metrics.</p><p>The project does not connect to GA4, query data, or verify values in reports. If the YAML says that engagementRate is calculated from engagedSessions and sessions, this defines the meaning of the metric but does not prove that a particular report actually calculates it in exactly the same way.</p><p>It also does not replace BI, a semantic layer, or DataLayer as Code. These layers solve different problems.</p><p>DataLayer as Code describes the events and parameters being collected. A semantic layer connects metrics, dimensions, and business entities. BI is responsible for presenting and using data in reports. Metrics as Code has a narrower role: it records what a specific metric means and which definition its semantics are based on.</p><p>This boundary is intentional. The narrower the responsibility of the contract, the easier it is to keep it understandable, verifiable, and independent of a specific calculation or visualization tool.</p><h3>What remains unresolved</h3><p>The current implementation still has two clear gaps.</p><p>The first is between definition and implementation.</p><p>Metrics as Code can formally describe what a metric means, which components it contains, and which source its semantics are based on. But this does not confirm that a specific implementation in GA4, BI, or another layer calculates it in full accordance with that definition.</p><p>The definition is validated for structure and internal consistency, but not against the implementation.</p><p>The second gap is between Metrics as Code and other contracts.</p><p>For example, ecommercePurchases can be defined as a metric that includes only the purchase event. The purchase event itself is described separately in DataLayer as Code.</p><p>At the moment, that relationship exists only as text inside definition. It is understandable to a person, but it is not a formal machine-readable relationship between the two repositories.</p><p>Both contracts exist, but they do not yet form a connected model.</p><h3>The next layer</h3><p>DataLayer as Code answers the question: <strong>what was collected</strong>.</p><p>Metrics as Code answers the next one: <strong>what does the number mean</strong>.</p><p>The next step in Analytics Context as Code is to make relationships between events, metrics, dimensions, and business entities explicit and machine-readable.</p><p>The goal is not to add more descriptions inside Metrics as Code, but to connect separate contracts through stable identifiers and formal relationships.</p><p>Then AI gets a connected structure rather than a set of independent definitions, and those relationships no longer have to be reconstructed from text.</p><p>In this sense, Metrics as Code is not the end of Analytics Context as Code, but another separate layer that can now be formally connected to the others.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=90ba6fa829ff" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Contract Survived Production. The Monolith Did Not.]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/the-contract-survived-production-the-monolith-did-not-a48a56140b11?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/a48a56140b11</guid>
            <category><![CDATA[web-analytics]]></category>
            <category><![CDATA[datalayer]]></category>
            <category><![CDATA[digital-analytics]]></category>
            <category><![CDATA[tracking]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Tue, 21 Jul 2026 05:38:09 GMT</pubDate>
            <atom:updated>2026-07-21T05:38:09.946Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*T7NMch2GKoYdVl0KcRbzLQ.png" /></figure><p><strong>TL;DR:</strong> In March I published <a href="https://github.com/dgizdevans/ga4-datalayer-as-code">ga4-datalayer-as-code</a>, a strict machine-readable contract for the GA4 data layer. Then I ran the same Data-Layer-as-Code approach in an enterprise production environment, and production had opinions. The contract idea held. The monolithic format did not: one 3,588-line JSON Schema does not scale in a review process. Version 5.0.0 is a full restructure into composable per-event schemas: 48 event files, 7 shared definition schemas composed via allOf + $ref, unevaluatedProperties instead of additionalProperties, paired validated examples, generated docs, and a CI-ready npm run validate.</p><p>This post continues that line. In <a href="https://medium.com/@dmitrijs.gizdevans/before-asking-ai-for-insights-give-it-a-contract-a9a53948c06f">Before Asking AI for Insights, Give It a Contract</a> I argued that AI on top of tracking is only as reliable as the contract underneath it. In <a href="https://medium.com/@dmitrijs.gizdevans/mcp-in-analytics-a-useful-interface-but-not-a-source-of-understanding-60602d95703d">MCP in analytics: a useful interface, but not a source of understanding</a> I argued that access to the stack is not the same as a described system that AI can reason on. This post is the next step: what that contract actually looks like in code after it has been through real implementation, real PRs, and real disagreements about payloads.</p><h3>Where the previous version stood</h3><p>The previous version was one YAML contract plus one monolithic JSON Schema of 3,588 lines, five example payloads, and a set of npm scripts named per example (validate:add_to_cart, validate:purchase, and so on).</p><p>As a proof of concept, it worked. As a living artifact in a team workflow, it had three concrete problems.</p><p>First, the diff. Every change, whether you added a parameter to one event or fixed a typo in a description, produced a diff inside one giant file. Reviewers saw “schema changed, +14 −3 somewhere around line 2,100” and had to reconstruct the intent themselves. A contract you cannot review is a contract in name only.</p><p>Second, duplication. The human-readable YAML and the machine-readable JSON Schema described the same thing twice. Two representations of one truth is an invitation for them to disagree.</p><p>Third, drift. They did disagree. Small edits landed in one form and not the other, and after a few iterations nobody could say with confidence which file was the source of truth. Which was exactly the disease the repository existed to cure.</p><h3>What changed, and why</h3><h3>1. One schema file per event</h3><p>Problem: unreadable PRs against a monolith. Solution: schema/events/{event}.json, 48 files, one per event. A PR that changes begin_checkout touches begin_checkout.json and its paired example, nothing else. The diff is the contract change. Review stops being archaeology.</p><h3>2. Shared definitions as composable schemas</h3><p>Splitting the monolith naively would copy the envelope fields, common web params, and the item schema into 48 places. Instead, shared definitions live once in schema/shared/ (envelope, common_web_params, identity_params, item, items, single_item, money_dependency) and every event composes them:</p><pre>&quot;allOf&quot;: [<br>  { &quot;$ref&quot;: &quot;../shared/envelope.json&quot; },<br>  { &quot;$ref&quot;: &quot;../shared/common_web_params.json&quot; },<br>  { &quot;$ref&quot;: &quot;../shared/money_dependency.json&quot; }<br>]</pre><p>A field is defined once. Fixing a definition fixes it in every event that references it.</p><h3>3. unevaluatedProperties instead of additionalProperties</h3><p>This is the technically interesting one, and the reason many teams give up on strict composed schemas.</p><p>In v4, strictness came from additionalProperties: false. That works in a monolith where every event branch inlines all of its fields. It breaks the moment you compose. additionalProperties is evaluated locally: it only sees properties declared in the same schema object. It cannot see properties that arrive through an allOf reference. So a composed purchase schema with additionalProperties: false would reject user_id, a perfectly valid envelope field, because user_id is declared in envelope.json, not in purchase.json.</p><p>At that point you have two bad options: re-declare every shared field in every event (duplication again), or drop strictness (undeclared fields flow through silently). Draft 2020–12 gives you a third one. unevaluatedProperties: false is evaluated against the whole composed result: everything declared inline plus everything declared in the referenced schemas counts as evaluated, and anything else fails. Strictness and composition stop being a trade-off.</p><h3>4. examples instead of enum on custom parameters</h3><p>In v4 logic, a custom parameter like customer_type wants an enum: [&quot;new&quot;, &quot;returning&quot;], closed list, maximum strictness. In production this failed in a predictable way. Business-defined values are not a closed set. The business adds a segment, the payload is correct by every reasonable standard, and validation fails anyway. After enough false alarms, people stop trusting the validator, which is worse than not having one.</p><p>So the rule in v5 is: enum is reserved for genuinely closed lists defined by an external standard or by the schema itself. Business-defined custom parameters document their known values through examples:</p><pre>&quot;customer_type&quot;: {<br>  &quot;type&quot;: &quot;string&quot;,<br>  &quot;description&quot;: &quot;Custom parameter classifying the buyer.&quot;,<br>  &quot;examples&quot;: [&quot;new&quot;, &quot;returning&quot;]<br>}</pre><p>The values are still documented, still visible to a developer and to an AI system reading the contract. They just do not break the build when reality grows.</p><h3>5. Grep-able governance metadata</h3><p>Here is an honest admission: the proof of concept did not touch privacy at all. It described event names, parameters, and types, and stopped there. Real implementation made the gap visible immediately, because in production the first questions about a tracking contract are not about payload shape. They are: what here is personal data, what is sensitive, who is allowed to see it, and can you prove your answer.</p><p>So in v5 every event carries x-event-class (auto_collected, enhanced_measurement, ecommerce, recommended) and every field carries x-pii and x-sensitivity. This turns governance questions into one-liners. &quot;What do we collect that is sensitive?&quot; is grep -rl &#39;&quot;x-sensitivity&quot;: &quot;low&quot;&#39; schema/. No spreadsheet, no separate inventory that goes stale, the answer lives in the same files the validator runs on.</p><h3>6. Paired examples enforced by the validator</h3><p>Every event schema has exactly one schema/examples/{event}.example.json. The validator does not treat examples as decoration: a schema without an example fails, an orphan example without a schema fails, an example that does not validate against its schema fails. Examples become executable documentation. If the contract changes and the example was not updated, CI tells you before a developer copies a stale payload.</p><h3>7. Generated index and docs</h3><p>v4 maintained the human-readable YAML next to the machine-readable schema. v5 removes the parallel form entirely. schema/index.json and docs/EVENTS.md are build artifacts produced by npm run generate. The readable form is derived from the machine-readable form, never edited by hand, so drift between them is structurally impossible.</p><h3>8. CI-ready validation</h3><p>The per-example scripts are gone. npm run validate compiles all 48 schemas against draft 2020-12 and validates all 48 examples. Wire it into CI and a contract violation fails the build before release, not in a dashboard three weeks later.</p><h3>One event, before and after</h3><p>Here is add_to_cart as it lived inside the v4 monolith, one of dozens of branches under $defs, with every shared field inlined:</p><pre>&quot;Event_add_to_cart&quot;: {<br>  &quot;type&quot;: &quot;object&quot;,<br>  &quot;additionalProperties&quot;: false,<br>  &quot;properties&quot;: {<br>    &quot;event_id&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;description&quot;: &quot;Optional deduplication / trace identifier&quot; },<br>    &quot;user_id&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;maxLength&quot;: 256, &quot;description&quot;: &quot;Known non-PII user identifier&quot; },<br>    &quot;user_properties&quot;: {<br>      &quot;type&quot;: &quot;object&quot;,<br>      &quot;additionalProperties&quot;: { &quot;type&quot;: [&quot;string&quot;, &quot;number&quot;, &quot;boolean&quot;, &quot;null&quot;] },<br>      &quot;description&quot;: &quot;GA4 user properties&quot;<br>    },<br>    &quot;debug_mode&quot;: { &quot;type&quot;: &quot;boolean&quot; },<br>    &quot;language&quot;: { &quot;type&quot;: &quot;string&quot; },<br>    &quot;page_location&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;maxLength&quot;: 1000 },<br>    &quot;page_referrer&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;maxLength&quot;: 420 },<br>    &quot;page_title&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;maxLength&quot;: 300 },<br>    &quot;screen_resolution&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;pattern&quot;: &quot;^\\d+x\\d+$&quot; },<br>    &quot;event&quot;: { &quot;const&quot;: &quot;add_to_cart&quot; },<br>    &quot;currency&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;pattern&quot;: &quot;^[A-Z]{3}$&quot;, &quot;description&quot;: &quot;ISO 4217 currency code&quot; },<br>    &quot;value&quot;: { &quot;type&quot;: &quot;number&quot; },<br>    &quot;items&quot;: { &quot;$ref&quot;: &quot;#/$defs/ItemsArray&quot; }<br>  },<br>  &quot;required&quot;: [&quot;event&quot;, &quot;items&quot;],<br>  &quot;dependentRequired&quot;: { &quot;value&quot;: [&quot;currency&quot;] }<br>}</pre><p>Every one of the 48 events repeated that envelope and page-context block. And here is the same event as a standalone file in v5, schema/events/add_to_cart.json:</p><pre>{<br>  &quot;$schema&quot;: &quot;https://json-schema.org/draft/2020-12/schema&quot;,<br>  &quot;title&quot;: &quot;add_to_cart&quot;,<br>  &quot;description&quot;: &quot;Item(s) added to the cart.&quot;,<br>  &quot;type&quot;: &quot;object&quot;,<br>  &quot;x-event-class&quot;: &quot;ecommerce&quot;,<br>  &quot;allOf&quot;: [<br>    { &quot;$ref&quot;: &quot;../shared/envelope.json&quot; },<br>    { &quot;$ref&quot;: &quot;../shared/common_web_params.json&quot; },<br>    { &quot;$ref&quot;: &quot;../shared/money_dependency.json&quot; }<br>  ],<br>  &quot;required&quot;: [&quot;event&quot;, &quot;items&quot;],<br>  &quot;properties&quot;: {<br>    &quot;event&quot;: { &quot;const&quot;: &quot;add_to_cart&quot; },<br>    &quot;currency&quot;: {<br>      &quot;type&quot;: &quot;string&quot;,<br>      &quot;pattern&quot;: &quot;^[A-Z]{3}$&quot;,<br>      &quot;description&quot;: &quot;ISO 4217 currency code. Required whenever value is present.&quot;,<br>      &quot;examples&quot;: [&quot;EUR&quot;],<br>      &quot;x-pii&quot;: false,<br>      &quot;x-sensitivity&quot;: &quot;none&quot;<br>    },<br>    &quot;value&quot;: {<br>      &quot;type&quot;: &quot;number&quot;,<br>      &quot;description&quot;: &quot;Monetary value of the event in the given currency.&quot;,<br>      &quot;examples&quot;: [129.99],<br>      &quot;x-pii&quot;: false,<br>      &quot;x-sensitivity&quot;: &quot;none&quot;<br>    },<br>    &quot;items&quot;: { &quot;$ref&quot;: &quot;../shared/items.json&quot; }<br>  },<br>  &quot;unevaluatedProperties&quot;: false<br>}</pre><p>Everything event-specific is visible in one screen. Everything shared arrives through composition. The value ⇒ currency rule is no longer copy-pasted per event: it is money_dependency.json, composed only onto events where value is monetary. earn_virtual_currency and spend_virtual_currency intentionally omit it, because virtual currency has no ISO code.</p><h3>Proof of strictness: what the validator rejects</h3><p>Strictness claims are cheap, so here are actual verdicts against the purchase schema.</p><p>A payload with transactionID instead of transaction_id is rejected: required transaction_id is missing and transactionID is an unevaluated property. The exact class of silent casing bug that survives for months in loosely validated setups dies at the build step.</p><p>A payload with value but no currency is rejected by the composed money_dependency rule: currency is required whenever value is present.</p><p>A payload with an undeclared top-level field is rejected by unevaluatedProperties: false. Undeclared fields are contract violations, not extensions.</p><p>And one that passes: an item-level custom parameter like stock_status inside items. Item-scoped extensibility is explicitly allowed through patternProperties in the shared item schema, with a cap, because GA4 itself allows item-scoped custom parameters and the contract should model reality, not fight it.</p><p>Rejecting the wrong things and accepting the right ones is the whole job of a contract.</p><h3>What the contract covers</h3><p>All 35 GA4 web recommended events published by Google, split into 14 ecommerce and 21 other recommended events, plus the baseline of 10 enhanced measurement events and 3 auto-collected events: 48 event schemas total, each with a validated example.</p><p>App-only recommended events are deliberately out of scope. This is a contract for dataLayer.push(...) on the web. App events travel through the Firebase SDK and never pass through a web data layer, so including them would describe payloads this contract can never validate.</p><p>If you want to see the restructure in full, the diff is public: <a href="https://github.com/dgizdevans/ga4-datalayer-as-code/compare/v4.0.0...v5.0.0">v4.0.0…v5.0.0</a>. One monolith out, 48 composable contracts in.</p><h3>Back to the bigger argument</h3><p>Nothing in my core argument has changed since the previous two posts. AI on top of analytics does not need more access, it needs a described system: definitions, rules, relationships, ownership. A tracking contract is the piece of that description I can actually ship as code.</p><p>What production changed is my sense of what that contract has to look like to actually matter. A contract that exists but cannot be reviewed, that duplicates itself and slowly drifts, is not structured context. It is just one more artifact quietly decaying in a repo, and everyone learns to work around it. The version that survives is the one a reviewer can actually read, a team can fix in one place, a pipeline can run on every release, and an AI system can load as context without me standing next to it explaining what the fields really mean.</p><p>Not because composition is more elegant. Because it stays true.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a48a56140b11" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your tracking has a second reader now]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/your-tracking-has-a-second-reader-now-01252f586122?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/01252f586122</guid>
            <category><![CDATA[tracking]]></category>
            <category><![CDATA[web-analytics]]></category>
            <category><![CDATA[datalayer]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Mon, 22 Jun 2026 17:32:06 GMT</pubDate>
            <atom:updated>2026-06-22T17:32:06.706Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IR9VWFQIm8v3m-elJHDrSA.png" /></figure><p><strong>TL;DR: </strong>→ Tracking has always been designed for one reader: a human looking at a report. A model is now a second reader of the same events, and it reads them in the opposite way.</p><p>→ Human-readable design compresses behavior: sequence into counts, values into Other, timing dropped. That is exactly the part a model would learn from.</p><p>→ The fix is not keeping everything. Raw high-cardinality fields break a model as badly as over-averaging. The goal is controlled resolution: keep the gradation that carries behavior, drop the variability that carries only uniqueness.</p><p>→ One governed event serves both readers. Reporting consumes a compressed view, the model consumes the full resolution, from the same source.</p><p>→ ML-only signals need stricter governance, not looser. A broken name, a changed type, a shifted consent state is caught by a human in a report and passes silently into a model. Quality is decided upstream, in event design, not in the model.</p><p><strong>The second reader</strong></p><p>Tracking was always designed for one reader. Not by decision, but because there was no other. User behavior was collected for a person to read: an analyst in a report, a marketer in a dashboard, a product manager in a funnel. The only audience for behavioral data was a human, and the whole event design quietly assumed it. Event names a human can read. Parameters in the categories a human thinks in. Granularity exactly as fine as a human can hold in their head while looking at a report.</p><p>Now behavior has a second reader. A model consumes the same events but reads them in a completely different way than a human does. And this is where a divergence starts that almost nobody builds into the design: data that is perfectly prepared for human reading often turns out worse for a model than it looks. Not because it is dirty. Because it is optimized for a different reader.</p><p>This is not a question of giving the ML team access to the data. It is a question of who the event was designed for at the moment of collection. A human and a model put different demands on the same data, and most of the time those demands pull in opposite directions.</p><p><strong>Where human-readable tracking compresses behavior</strong></p><p>For a human to read behavior, it has to be compressed. A person does not read a raw event stream, they read the result of a rollup: how many, on average, in which category, compared to last week. Every layer on the path from event to report collapses something, and that is not a defect, that is the job of the reporting layer. The problem is not compression. The problem is that compression happens for the human by default, before anyone asks whether the model needs what gets lost.</p><p><strong>Look at what exactly gets thrown away along the way.</strong></p><p>Sequence collapses into counts. In a report a human needs to know that a form step was completed 10000 times. The order in which a specific user moved through the steps, went back, dropped off and came back does not make it into the count. For a funnel that is enough. The behavioral trajectory disappears in the process.</p><p>Values collapse into categories. Dozens of different behaviors get reduced to a few readable buckets, and the long tail goes into Other. Other is convenient for a human, it removes noise from the table. But Other is not nothing, it is discarded variability, and sometimes the signal is exactly there.</p><p>Timing gets rounded or dropped. In a report the date matters, sometimes the hour. Intervals between actions, pauses, the speed of moving through steps are almost always lost at the report level, because a human has nothing to do with them while looking at a dashboard.</p><p>In all three cases the logic is the same: keep what a human can read, drop what they cannot hold. That is right for a report. But this decision about what counts as signal and what counts as noise is made based on what a human can do, not on what could be learned from the data. And it is made quietly, as an implicit design choice, not as a deliberate one. By this point the second reader has already lost part of what it could have learned from, and nobody noticed.</p><p><strong>Why models read behavior differently</strong></p><p>Take a concrete event. A form step that fires every time a user moves to the next step of a multi-step form. The minimal payload looks roughly like this:</p><pre>event: form_step<br>session_id: 9f3c4b7e-a21d<br>form_id: checkout<br>step_index: 2<br>step_name: shipping<br>timestamp: 2026-01-14T10:32:08.521Z</pre><p>Nothing extra: which session, which form, which step, what it is called, when it happened. Now look at what a report builds from this event and what a model sees in the same one.</p><p>The report builds a funnel. It takes step_index, counts how many users reached each step, and outputs the conversion rate between steps and the overall drop-off. timestamp collapses to the day, step_name becomes an axis label. The output is a table: step 1 — 10000, step 2 — 7400, step 3 — 5100. A human looks and sees where the form loses people. For that task the event is perfect.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-8b9uloqPJFREFnkYGF_GQ.png" /></figure><p>A model sees something else in the same event. Not an aggregate per step, but the trajectory of a specific session over time. The sequence of steps in the order they were taken: reached 2, went back to 1, on to 2 again, left. The intervals between steps: three seconds between the first and the second, a forty second pause before the third. Speed, hesitation, repeat visits. For a model this is not noise around the conversion rate, this is the behavior that separates a user who will leave from a user who will finish.</p><p>The difference is not that the model has more data. The data is the same, the same event. The difference is that reporting reads it as a point in an aggregate, and a model reads it as a link in a sequence. The report asks how many are on this step. The model asks what happened before and after, and how fast. The same form_step answers both questions, but only if order and time are preserved at collection. Collapse them for the report, and nothing changes for the funnel, while for the model the event goes mute.</p><p>This is where human-readable design and machine-readable design first diverge on a concrete field. Not on data quality, but on what reaches the second reader at all.</p><p><strong>Resolution, not more data</strong></p><p>It is easy to draw the wrong conclusion: if the model feeds on what the report throws away, you should just keep everything. More fields, more precision, collapse nothing. That is a mistake, and it breaks the model just as reliably as over-averaging does.</p><p>Back to the same form_step. The interval between steps is signal: three seconds versus forty say different things about behavior. But a precise timestamp down to the millisecond as a feature is not signal, it is noise the model overfits to. 2026-01-14T10:32:08.521Z will never repeat. As a feature it carries no behavior, it carries uniqueness, and a model given that field raw will start latching onto meaningless coincidences. What is useful is not the timestamp but what is derived from it: the interval between steps, time to first action, recency, session length. The same underlying timing can be signal or noise, the difference is whether it was prepared or left raw.</p><p>The same goes for any high-cardinality field. A raw session id, free text from an input field, an exact coordinate, the full user agent are all variability with no behavioral meaning. A model does not learn a pattern from it, it memorizes specifics and performs worse on new data. A report is protected from such a field because a human simply will not put it on an axis. A model has no such protection, it will take whatever it is given.</p><p>So the right goal is not resolution and not compression, it is controlled resolution. The question on every field is one: does this gradation carry behavior or only uniqueness. The interval between steps carries it, the millisecond does not. The order of steps carries it, a random id does not. This decision is made when the event is designed, not in the model, because by the time the data reaches the model the choice is already made: either the needed gradation is preserved, or it was lost in compression, or it was drowned in cardinality. All three outcomes are the result of how the event was designed.</p><p>More data and better for the model are not the same thing. A good event gives the model not the maximum detail, but the resolution it can actually learn from. Separating gradation that carries behavior from variability that carries nothing is the work that human-oriented design never did, because the human did it themselves, by refusing to look at the extra fields.</p><p><strong>Governance for machine-readable tracking</strong></p><p>Say the event is collected correctly and at the right resolution. It will not stay correct on its own. Its name, its parameters, its consent state, its owner change over time, and this is where the divergence between the two readers becomes most dangerous. Because in reporting a human catches the distortion, and in an ML-only stream there is nobody to catch it.</p><p>Take naming. For a report form_step_v2 next to the old form_step is a minor inconvenience, a human sees both and understands it is the same event after a redesign. For a model these are two different features. The stability of a name, which a human barely cares about, is for a model the condition of learning from continuous behavior at all, rather than from two disconnected histories before and after the rename.</p><p>Take parameters. A person building a report will notice if step_index suddenly starts arriving as a string instead of a number, because their sorting falls apart. A model will not notice, it will swallow it and keep learning on the corrupted field, and the only trace will be a quietly degraded prediction quality that nobody connects to a parameter type that changed half a year ago.</p><p>Take consent. In a report a dropped consent shows up as a drop in volume, a human notices there are fewer rows. In an ML-only stream a shifted consent perimeter is not visible at all: the model simply starts learning on a skewed sample where a whole segment of users has disappeared, and produces confident predictions on data that is no longer representative. No drop in the dashboard, because there is no dashboard in that loop.</p><p>Take ownership. As long as an event has an owner who knows what it is for and what each field means, the definition holds. Once the owner is lost, the event runs on inertia, and its meaning starts to diverge from how the model reads it. For a report that is tolerable, a human asks a colleague. For a model the definition is the contract, and lost ownership is a contract with no party answering for it.</p><p>In all four cases the pattern is the same. What is a mere inconvenience in reporting, because a human is in the loop and will catch it, becomes a silent failure in machine-readable tracking, because there is no human in the loop. Monitoring and drift checks catch some of it, but they see that the distribution moved, not why. The cause, a broken name, a changed type, a shifted consent state, stays upstream, in the design of the event. So governance for machine-readable tracking needs to be not the same as for reports, but stricter. Not because the data matters more, but because there is nobody to notice when it starts to lie.</p><p>The quality of what a model learns is not decided in the model. It is decided where the event is designed, named, typed and assigned to an owner. Upstream, before the first feature ever reaches training.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=01252f586122" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[MCP in analytics: a useful interface, but not a source of understanding]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/mcp-in-analytics-a-useful-interface-but-not-a-source-of-understanding-60602d95703d?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/60602d95703d</guid>
            <category><![CDATA[web-analytics]]></category>
            <category><![CDATA[digital-analytics]]></category>
            <category><![CDATA[mcp-protocol]]></category>
            <category><![CDATA[tracking]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Tue, 05 May 2026 10:14:59 GMT</pubDate>
            <atom:updated>2026-05-05T10:14:59.034Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YkOHlKiOessdVWok_cmcWw.png" /></figure><p><strong>TL;DR</strong>: MCP is a transport layer, not a source of understanding. AI through MCP can pull data from the analytics stack faster, but without structured context (metric catalog, semantic layer, lineage, baselines, ownership, source of truth, rules, business context) it produces quick guesses rather than grounded reasoning. The real question isn’t “can we connect AI to the stack” but “is the stack described well enough for AI to reason on top of it reliably”.</p><p>There are growing expectations around MCP in connection with the analytics stack: GA4, Adobe Analytics, BigQuery, BI tools, tracking plans, and internal systems.</p><p>This is an understandable trend. MCP can indeed be a useful infrastructure layer. It standardizes access for AI systems to tools, data sources, and workflows. For teams where data and context are scattered across different systems, this looks very attractive.</p><p>But it is important not to overestimate the role of MCP itself. MCP alone does not create analytical understanding. It is an interface layer, not a semantic layer, not a metric model, not a baseline, not a source of business context, and not a replacement for analytics discipline.</p><h3>What MCP can actually provide</h3><p>An AI assistant connected through MCP can be useful in analytics work. It can find obvious patterns faster, compare segments, check changes, look for correlations, and help with initial issue investigation.</p><p>For example, it can show that a specific metric dropped in a specific country, on a specific device, after a specific release or a change in the tracking setup.</p><p>That is useful. Especially if an analyst previously had to open GA4, Adobe Analytics, BigQuery, Jira, Tealium / GTM changelogs, BI dashboards, tracking documentation, and several internal tables just to collect the initial context.</p><p>In this sense, an AI assistant using MCP as an interface can reduce the manual effort needed to collect evidence. It can more quickly access available specs, SQL queries, dashboards, changelogs, ownership information, and related system changes.</p><p>But this only works if those artifacts actually exist, are up to date, and are accessible. If tracking documentation is outdated, changelogs are incomplete, ownership is not described, and the source of truth is not defined, AI cannot compensate for that gap with a single MCP connection. At best, it will more quickly show where the required context is missing.</p><p>Faster access to information is still not the same as understanding information.</p><p>In analytics, this distinction matters. Finding a time-based correlation is not the same as establishing causation. Seeing a metric drop is not the same as understanding whether tracking broke, user behavior changed, a release had an impact, traffic mix shifted, or the issue sits outside the analytics system entirely.</p><h3>Where MCP does not solve the core problem</h3><p>In many organizations, the main analytics problems are not about access to data. They sit deeper.</p><p><strong>Unclear metric definitions.</strong> The same metric can mean different things to marketing, product, finance, and analytics teams. For example, “conversion rate”, “checkout started”, or “active user” can be calculated using different rules in different reports. If this is not explicitly documented, AI cannot reliably understand which business logic is being discussed.</p><p><strong>Weak or missing baselines.</strong> It is not always clear what should be considered normal metric behavior. Without a baseline, AI can detect an increase or decrease, but it cannot reliably understand whether it is an anomaly, seasonality, a channel effect, or normal fluctuation.</p><p><strong>Poor tracking documentation.</strong> Events may exist in GA4, Adobe Analytics, or BigQuery, but their purpose, firing conditions, parameters, and limitations are often incomplete or outdated. As a result, AI may see an event name but still not understand what the event actually represents.</p><p><strong>No event lineage.</strong> It is not always clear where an event comes from, where it is created, how it moves through GTM, SDK, backend, and the data warehouse, or which downstream metrics depend on it. Without this connection, it is hard to understand whether the issue is a tracking issue, a data pipeline issue, or a real change in user behavior.</p><p><strong>Unclear ownership model.</strong> When a metric, event, dashboard, or pipeline breaks, it is not always clear who owns it: analytics, marketing, product, engineering, data team, or an external platform. AI can find a problem, but without an ownership model it cannot help route it to the right owner.</p><p><strong>Conflicts between data sources and unclear source of truth.</strong> GA4, Adobe Analytics, backend, CRM, payment providers, and BigQuery can show different numbers. This is normal in complex systems, but only if interpretation rules exist: which source to use for which question, where data is considered final, which discrepancies are acceptable, and who makes the decision when sources conflict. Without these rules, AI does not know which source should be trusted in a specific case.</p><p><strong>Chaotic dashboards.</strong> There may be many reports, but they often duplicate each other, use different filters, rely on different metric definitions, and do not explain how decisions should be made based on them. AI can get access to dashboards, but that does not mean the dashboards contain a correct decision-making logic.</p><p><strong>No investigation playbooks.</strong> When a metric drops, there is often no agreed process: what to check first, how to distinguish a tracking issue from a real behavior change, which sources to inspect, and in what order. Without a playbook, AI has to reconstruct the investigation from scratch every time and can easily drift into shallow hypotheses.</p><p><strong>Weak business context.</strong> Data alone may not contain information about promotions, seasonality, local market specifics, product changes, campaigns, known issues, or organizational decisions that affect metric interpretation. Without this, AI can see the numbers but not understand the context in which they appeared.</p><p>Data literacy is a separate issue. Even if the technical system is well described, stakeholders may still expect AI to deliver “ready-made insights” without understanding the limitations of the data: sampling, attribution, consent impact, tracking gaps, segmentation, or the difference between correlation and causation. In that case, AI may not improve understanding; it may simply package a weak question into a confident-sounding answer more quickly.</p><p>In this environment, MCP does not solve the core problem. It simply gives AI more convenient access to the same unresolved system.</p><h3>What context AI needs beyond MCP</h3><p>For AI to reason more reliably on top of the analytics stack, it needs more than access through MCP. It needs structured context around the data:</p><ul><li><strong>event and parameter catalog</strong>: which events exist, what they mean, when they should fire, which parameters they send, which values are valid, which parameters are required or optional, and what limitations the event has;</li><li><strong>metric catalog</strong>: what each metric means and how it is calculated;</li><li><strong>semantic layer</strong>: how entities, events, metrics, and dimensions are connected;</li><li><strong>event lineage</strong>: where an event comes from and which downstream metrics depend on it;</li><li><strong>baselines</strong>: what normal behavior looks like by country, device, channel, and time period;</li><li><strong>data quality rules</strong>: which checks define whether data is broken or incomplete;</li><li><strong>ownership model</strong>: who owns a metric, event, dashboard, or pipeline;</li><li><strong>source of truth rules</strong>: which source should be trusted when data does not match;</li><li><strong>change logs</strong>: which releases, GTM publications, experiments, or settings could have affected the data;</li><li><strong>investigation playbooks</strong>: in what order hypotheses should be checked;</li><li><strong>business context</strong>: seasonality, campaigns, promotions, market-specific behavior, and known issues.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*T0jymaXR8bX-DWQNyu29xg.png" /><figcaption><em>MCP gives AI access to raw analytics tools. Structured context — metric catalog, semantic layer, lineage, baselines, ownership, rules — describes those tools and makes their data interpretable.</em></figcaption></figure><p>This is the layer that makes an AI assistant potentially useful in analytics. Not the fact that it is connected to GA4, Adobe Analytics, BigQuery, or Jira, but the fact that there is a described system on top of which AI can reason.</p><p>MCP can provide access to all of this, but it does not create it. More data does not mean more understanding, more integrations do not mean better decisions, and access to tools does not replace methodology.</p><h3>The main question</h3><p>For analytics use cases, MCP can be a very useful plumbing layer. It can reduce manual context gathering, speed up investigations, and make it easier to work with fragmented sources.</p><p>But expecting one AI connection to the analytics stack to suddenly produce reliable insights is an inflated expectation.</p><p>The main question is not whether we can connect AI to our analytics stack. The main question is whether the analytics stack itself is described well enough for AI to reason on top of it reliably.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*eWb7BNv_4qm4mF0vp-J8SQ.png" /><figcaption><em>Same MCP, same raw tools — but loading structured context into AI as system instructions or RAG changes what AI sees and what kind of output it can produce.</em></figcaption></figure><p>Understanding appears only when the system already contains definitions, relationships, rules, context, and accountability.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=60602d95703d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Chrome Soft Navigations API: A Possible Step Forward for SPA Tracking]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/chrome-soft-navigations-api-a-possible-step-forward-for-spa-tracking-15a708621f6f?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/15a708621f6f</guid>
            <category><![CDATA[web-analytics]]></category>
            <category><![CDATA[tracking]]></category>
            <category><![CDATA[google-chrome]]></category>
            <category><![CDATA[sap]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Tue, 28 Apr 2026 06:41:04 GMT</pubDate>
            <atom:updated>2026-04-28T06:41:04.631Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZbxqiK9nlcionvjPgiPuDg.png" /></figure><p><strong>TL;DR</strong>: Chrome started the final origin trial of the Soft Navigations API in Chrome 147–149. For tracking, this is not a replacement for a router listener. It is an independent browser-level signal that the user went through a page-like transition.</p><p>The practical value is SPA pageview audit: compare browser-detected soft navigations with current virtual pageviews and find missing, duplicate or mistimed events.</p><p>The API does not solve data layer timing, consent or business definitions. The payload still has to be assembled by the application.</p><blockquote><em>Note: this is a theoretical breakdown. The API is still in origin trial, and without a registered token or an enabled flag it cannot be tested as a normal production feature. The article describes how it could be used for tracking, not a report on a real rollout.</em></blockquote><h3>What happened</h3><p>In the last few years, SPA-style front ends have become the normal choice for many large ecommerce and product platforms. React, Vue, Angular, Next.js and similar frameworks made routing, async rendering, dynamic components, overlays and client-side transitions much easier for developers.</p><p>For tracking engineers, this is often painful.</p><p>Not because SPA tracking is impossible. The problem is that many important details are hidden inside framework and router behaviour. From the development side, it may look like normal application logic. From the tracking side, we still need to decide what is a real page-like transition, what is only a UI state change, where to send a virtual pageview, and where a normal event is enough.</p><p><a href="https://developer.chrome.com/blog/final-soft-navigations-origin-trial">Chrome has now started the final origin trial for the <strong>Soft Navigations API</strong> in Chrome 147–149</a>. Chrome plans to test the expected final shape of the API before a possible release later this year.</p><p>The practical interest is not just the API itself. The interesting part is that the browser is starting to formalize SPA transitions as a separate type of navigation. For tracking, this matters because a virtual pageview in SPA has never been only a technical event. It is also a semantic decision: what exactly do we call a new page when there is no full page load?</p><p>In a classic website, the model is simple:</p><blockquote><em>Page A -&gt; full page load -&gt; Page B</em></blockquote><p>There is a new document load. There is a browser navigation. There is a pageview. Performance metrics can be connected to that page load.</p><p>In SPA, the model is different:</p><blockquote><em>Page A -&gt; JavaScript updates route and content -&gt; Page B</em></blockquote><p>The URL can change. The main content can change. The user may clearly feel that they moved to a new page. But from the browser’s point of view, the original document is still the same document.</p><p>This gap between <strong>user-perceived navigation</strong> and <strong>technical page load</strong> is what the Soft Navigations API tries to reduce.</p><h3>Why a route listener does not solve everything</h3><p>On many SPA projects, the first version of tracking logic looks simple:</p><blockquote><em>route changed -&gt; send virtual_page_view</em></blockquote><p>For basic cases, this can work. But on a real ecommerce or product platform, edge cases appear very quickly.</p><blockquote><strong><em>PDP variant change</em></strong><em><br>Pageview or event?</em></blockquote><blockquote><strong><em>Checkout step change</em></strong><em><br>Pageview or event?</em></blockquote><blockquote><strong><em>Overlay with its own URL</em></strong><em><br>Pageview or event?</em></blockquote><blockquote><strong><em>Search filters update URL</em></strong><em><br>Pageview or event?</em></blockquote><blockquote><strong><em>Same route, new content</em></strong><em><br>Pageview or event?</em></blockquote><blockquote><strong><em>New route, same content</em></strong><em><br>Pageview or event?</em></blockquote><p>The hard part is not only how to send page_view. The hard part is who defines the line between a new page, a UI state change and a normal interaction event.</p><p>Another common problem is timing.</p><p>In SPA, the route can change before the data layer is ready. Or the virtual pageview can be sent before the app has loaded the new product, category or page attributes. As a result, analytics gets the new URL, but the old page_type, old product_id or incomplete context.</p><p>A typical issue:</p><blockquote><em>URL changed<br>-&gt; virtual_page_view fired<br>-&gt; product data updated after async request</em></blockquote><p>From the outside, tracking looks fine. The event was sent. The pageview exists. But the payload is already partly wrong.</p><p>This is why SPA tracking is not just “add a router listener”. The real challenge is to align three layers:</p><blockquote><em>user-visible navigation<br>application state<br>analytics payload</em></blockquote><p>When these layers are not aligned, we get the classic SPA tracking bugs: missing pageviews, duplicate pageviews, stale data, wrong attribution and inconsistent funnel steps.</p><h3>What Chrome calls a soft navigation</h3><p>A soft navigation is an SPA transition that looks like a navigation to the user, but does not create a normal browser navigation because no new document is loaded.</p><p>Chrome does not try to detect this only by checking if the URL changed. That is important.</p><p>A site can call history.pushState() or history.replaceState() for many reasons: filters, tabs, sorting, overlay state or other UI state. A URL update alone does not always mean a new page-like transition.</p><p>Chrome defines soft navigation around a combination of signals:</p><blockquote><em>user interaction</em></blockquote><blockquote><em>&gt; visible content paint</em></blockquote><blockquote><em>&gt; URL update<br>= possible soft navigation</em></blockquote><p>In simple words:</p><blockquote><em>user clicks something<br>-&gt; JavaScript handles the transition<br>-&gt; URL changes<br>-&gt; meaningful content changes on screen<br>-&gt; browser records a soft-navigation entry</em></blockquote><p><a href="https://developer.chrome.com/blog/final-soft-navigations-origin-trial">Chrome’s current documentation describes the trigger as: a user interaction occurs, it results in a visible paint, and a URL update occurs</a>.</p><p>This is different from a normal route listener.</p><p>A route listener knows that the route changed.<br>A browser-level soft navigation signal tries to detect whether the transition looked like a real navigation from the user’s point of view.</p><p>For tracking, this is useful as an extra validation layer.</p><p>Not just:</p><blockquote><em>router said route changed, so send pageview</em></blockquote><p>But:</p><blockquote><em>browser detected a user-visible SPA transition,<br>so we can check whether analytics sent the correct virtual pageview</em></blockquote><h3>How it differs from a normal virtual pageview</h3><p>A virtual pageview is usually created by the application or by the tracking implementation.</p><p>Example:</p><pre>router.afterEach((to) =&gt; {<br>  dataLayer.push({<br>    event: &quot;virtual_page_view&quot;,<br>    page_path: to.path<br>  });<br>});</pre><p>In this case, the source of truth is the application router.</p><p>That is normal, but it has a limit. The router tracks route changes. It does not always prove that the user experienced a meaningful page-like navigation.</p><p>Soft Navigations API adds another type of signal:</p><blockquote><em>browser detected a page-like SPA transition</em></blockquote><p>The difference is important.</p><p>virtual_page_view is an analytics event.<br>soft-navigation is a browser performance entry.</p><p>The first answers this question:</p><blockquote><em>What did we send to analytics?</em></blockquote><p>The second answers another question:</p><blockquote><em>Did the browser detect a user-visible SPA navigation?</em></blockquote><p>For tracking teams, the value is not to blindly replace router-based tracking with browser-based tracking.</p><p>The value is that we get an independent browser-level signal and can compare it with the current SPA tracking logic.</p><blockquote><strong><em>Case 1:</em></strong><em> Soft navigation detected, but no virtual pageview.<br></em><strong><em>Possible issue:</em></strong><em> missing pageview.</em></blockquote><blockquote><strong><em>Case 2:</em></strong><em> Virtual pageview sent, but no soft navigation detected.<br></em><strong><em>Possible issue:</em></strong><em> overtracking or different business definition.</em></blockquote><blockquote><strong><em>Case 3:</em></strong><em> Multiple virtual pageviews for one soft navigation.<br></em><strong><em>Possible issue:</em></strong><em> duplicate tracking.</em></blockquote><h3>How to catch it technically</h3><p>A soft navigation is exposed as a PerformanceEntry with the type soft-navigation.</p><p>It is not a DOM event.<br>It is not click.<br>It is not a ready-made GTM trigger.</p><p>It is a Performance Timeline entry that can be observed with PerformanceObserver.</p><p>Basic support check:</p><pre>const supportsSoftNavigation =<br>  &quot;SoftNavigationEntry&quot; in window ||<br>  PerformanceObserver.supportedEntryTypes?.includes(&quot;soft-navigation&quot;);<br>if (supportsSoftNavigation) {<br>  console.log(&quot;Soft Navigation API is supported&quot;);<br>}</pre><p>Basic listener:</p><pre>if (supportsSoftNavigation) {<br>  const observer = new PerformanceObserver((list) =&gt; {<br>    for (const entry of list.getEntries()) {<br>      console.log(&quot;Soft navigation detected:&quot;, entry);<br>    }<br>  });<br><br>observer.observe({<br>    type: &quot;soft-navigation&quot;,<br>    buffered: true<br>  });<br>}</pre><p><a href="https://developer.chrome.com/docs/web-platform/soft-navigations-experiment">Chrome documentation shows the same observation model with </a><a href="https://developer.chrome.com/docs/web-platform/soft-navigations-experiment">PerformanceObserver and the </a><a href="https://developer.chrome.com/docs/web-platform/soft-navigations-experiment">soft-navigation entry type</a>.</p><p>For tracking and diagnostics, these fields are the most useful:</p><pre>entry.name<br>// New URL for the soft navigation<br><br>entry.entryType<br>// &quot;soft-navigation&quot;<br>entry.startTime<br>// Start time of the user interaction that initiated the soft navigation,<br>// reported relative to the initial hard navigation time<br>entry.duration<br>// Difference between presentationTime and startTime at the time of emission<br>entry.navigationId<br>// Pseudo-random number that increments with each new navigation<br>entry.interactionId<br>// Interaction that caused the soft navigation<br>entry.paintTime<br>// Paint timing for the first contentful paint of this soft navigation<br>entry.presentationTime<br>// Presentation timing for the first contentful paint of this soft navigation<br>entry.largestInteractionContentfulPaint<br>// Largest interaction-contentful-paint entry seen for this navigation so far<br>entry.navigationType<br>// Type of same-document navigation, for example push or replace</pre><p><a href="https://wicg.github.io/soft-navigations/?utm_source=chatgpt.com">The current WICG spec defines </a><a href="https://wicg.github.io/soft-navigations/?utm_source=chatgpt.com">SoftNavigationEntry and related fields</a>.</p><p>At this stage, I would not send a production pageview immediately from this listener. A safer first step is to log these entries and compare them with the current virtual pageviews.</p><h3>Example: send a diagnostic event to dataLayer first</h3><p>I would not start by sending an analytics pageview directly from the soft-navigation listener.</p><p>A safer first step is to push a separate diagnostic event to dataLayer, then compare it with existing virtual pageviews.</p><pre>(function () {<br>  const supportsSoftNavigation =<br>    &quot;SoftNavigationEntry&quot; in window ||<br>    PerformanceObserver.supportedEntryTypes?.includes(&quot;soft-navigation&quot;);<br>if (!supportsSoftNavigation) {<br>    return;<br>  }<br>  const observer = new PerformanceObserver((list) =&gt; {<br>    for (const entry of list.getEntries()) {<br>      window.dataLayer = window.dataLayer || [];<br>      window.dataLayer.push({<br>        event: &quot;soft_navigation_detected&quot;,<br>        soft_navigation_url: entry.name,<br>        soft_navigation_start_time: entry.startTime,<br>        soft_navigation_duration: entry.duration,<br>        soft_navigation_id: entry.navigationId || null,<br>        soft_navigation_interaction_id: entry.interactionId || null,<br>        soft_navigation_navigation_type: entry.navigationType || null,<br>        soft_navigation_paint_time: entry.paintTime || null,<br>        soft_navigation_presentation_time: entry.presentationTime || null,<br>        page_location: window.location.href,<br>        page_path: window.location.pathname<br>      });<br>    }<br>  });<br>  observer.observe({<br>    type: &quot;soft-navigation&quot;,<br>    buffered: true<br>  });<br>})();</pre><p>The idea is simple: do not change the current pageview logic immediately. First, collect browser-detected SPA navigations as a diagnostic layer.</p><p>Then compare:</p><blockquote><em>soft_navigation_detected<br>vs<br>virtual_page_view</em></blockquote><p>Examples:</p><blockquote><strong><em>Case 1:</em></strong><em> </em><em>soft_navigation_detected exists, but </em><em>virtual_page_view is missing.<br></em><strong><em>Possible issue:</em></strong><em> missing SPA pageview.</em></blockquote><blockquote><strong><em>Case 2:</em></strong><em> </em><em>virtual_page_view exists, but </em><em>soft_navigation_detected is missing.<br></em><strong><em>Possible issue:</em></strong><em> overtracking or intentional analytics-only pageview.</em></blockquote><blockquote><strong><em>Case 3:</em></strong><em> One </em><em>soft_navigation_detected, but multiple </em><em>virtual_page_view events.<br></em><strong><em>Possible issue:</em></strong><em> duplicate pageview.</em></blockquote><p>At this stage, soft_navigation_detected should not be treated as a pageview replacement. It is an audit signal. Its job is to show where browser-level SPA navigation and analytics implementation disagree.</p><h3>Example: Tealium utag.view</h3><p>In theory, a soft-navigation listener can be used as a trigger for utag.view().</p><p>But in production, this needs care. Most SPA sites already have pageview logic: router listeners, custom dataLayer events, framework hooks or direct utag.view() calls. If we add one more source without deduplication, we can easily create duplicate pageviews.</p><p>Simplified example:</p><pre>(function () {<br>  const supportsSoftNavigation =<br>    &quot;SoftNavigationEntry&quot; in window ||<br>    PerformanceObserver.supportedEntryTypes?.includes(&quot;soft-navigation&quot;);<br>if (!supportsSoftNavigation) {<br>    return;<br>  }<br>  const observer = new PerformanceObserver((list) =&gt; {<br>    for (const entry of list.getEntries()) {<br>      if (<br>        typeof window.utag !== &quot;undefined&quot; &amp;&amp;<br>        typeof window.utag.view === &quot;function&quot;<br>      ) {<br>        window.utag.view({<br>          tealium_event: &quot;virtual_page_view&quot;,<br>          page_url: entry.name,<br>          page_path: new URL(entry.name).pathname,<br>          navigation_type: &quot;soft_navigation&quot;,<br>          soft_navigation_id: entry.navigationId || null,<br>          soft_navigation_interaction_id: entry.interactionId || null,<br>          soft_navigation_navigation_type: entry.navigationType || null,<br>          soft_navigation_start_time: entry.startTime,<br>          soft_navigation_duration: entry.duration<br>        });<br>      }<br>    }<br>  });<br>  observer.observe({<br>    type: &quot;soft-navigation&quot;,<br>    buffered: true<br>  });<br>})();</pre><p>In a real implementation, I would add deduplication first:</p><pre>const sentSoftNavigations = new Set();<br>function shouldSendSoftNavigation(entry) {<br>  const key = [<br>    entry.navigationId || &quot;no-navigation-id&quot;,<br>    entry.interactionId || &quot;no-interaction-id&quot;,<br>    entry.name,<br>    entry.startTime<br>  ].join(&quot;|&quot;);<br>  if (sentSoftNavigations.has(key)) {<br>    return false;<br>  }<br>  sentSoftNavigations.add(key);<br>  return true;<br>}</pre><p>Then send utag.view() only after that:</p><pre>if (shouldSendSoftNavigation(entry)) {<br>  utag.view({<br>    tealium_event: &quot;virtual_page_view&quot;,<br>    page_url: entry.name,<br>    page_path: new URL(entry.name).pathname,<br>    navigation_type: &quot;soft_navigation&quot;,<br>    soft_navigation_id: entry.navigationId || null,<br>    soft_navigation_interaction_id: entry.interactionId || null,<br>    soft_navigation_navigation_type: entry.navigationType || null<br>  });<br>}</pre><p>Even with deduplication, one big question remains: is the data layer ready when the browser reports the soft navigation?</p><p>For Tealium, a more realistic model is:</p><blockquote><em>soft-navigation detected<br>-&gt; wait for application or dataLayer page context<br>-&gt; validate required fields<br>-&gt; send utag.view()</em></blockquote><p>Or, for the first test:</p><blockquote><em>soft-navigation detected<br>-&gt; push diagnostic event<br>-&gt; compare against existing utag.view calls</em></blockquote><p>So yes, soft-navigation can be a trigger candidate. But it should not automatically become the only source of SPA pageviews.</p><h3>Why it does not replace the data layer</h3><p>Soft Navigations API can help answer one specific question:</p><blockquote><em>Did a user-visible SPA navigation happen?</em></blockquote><p>But it does not answer the main tracking question:</p><blockquote><em>What exactly should be sent with this pageview?</em></blockquote><p>The browser can detect a soft navigation, but it does not know the business context of the page.</p><p>It does not know:</p><blockquote><em>page_type<br>page_name<br>site_section<br>product_id<br>product_sku<br>category_id<br>checkout_step<br>market<br>language<br>currency<br>customer_status<br>consent_state</em></blockquote><p>All of that still needs to come from the application, data layer, tag manager logic or enrichment layer.</p><p>The model is closer to this:</p><blockquote><strong><em>Soft Navigations API:</em></strong><em> navigation detection signal<br></em><strong><em>Data layer:</em></strong><em> business context<br></em><strong><em>Tag manager:</em></strong><em> routing, enrichment and mapping<br></em><strong><em>Analytics tools:</em></strong><em> reporting destination</em></blockquote><p>If the data layer updates late, contains stale values or does not cover important application states, the soft-navigation signal will not fix that.</p><p>Example:</p><blockquote><em>soft-navigation detected<br>-&gt; pageview fired<br>-&gt; page_type still contains previous page value</em></blockquote><p>Technically, the pageview exists.<br>Analytically, it is bad.</p><p>So the value of the API is not that it “solves SPA tracking”. It can help detect the moment and fact of a page-like transition, but payload quality still depends on the data layer and tracking specification.</p><h3>Where this can help tracking teams</h3><p>The first practical use case is <strong>SPA pageview audit</strong>.</p><p>You can collect two lines of data:</p><blockquote><strong><em>1.</em></strong><em> Current virtual pageviews from existing tracking implementation<br></em><strong><em>2.</em></strong><em> Browser-detected soft navigations</em></blockquote><p>Then compare them.</p><blockquote><strong><em>Case 1:</em></strong><em> Browser detects soft navigation, but analytics has no pageview.<br></em><strong><em>Possible issue:</em></strong><em> missing tracking.</em></blockquote><blockquote><strong><em>Case 2:</em></strong><em> Analytics has pageview, but browser detects no soft navigation.<br></em><strong><em>Possible issue:</em></strong><em> overfiring or intentionally broader pageview definition.</em></blockquote><blockquote><strong><em>Case 3:</em></strong><em> Multiple analytics pageviews for one soft navigation.<br></em><strong><em>Possible issue:</em></strong><em> duplicate tracking.</em></blockquote><blockquote><strong><em>Case 4:</em></strong><em> Soft navigation detected before business data is ready.<br></em><strong><em>Possible issue:</em></strong><em> timing problem.</em></blockquote><blockquote><strong><em>Case 5:</em></strong><em> Soft navigation detected, but </em><em>page_type is stale.<br></em><strong><em>Possible issue:</em></strong><em> wrong data layer update order.</em></blockquote><p>The second use case is <strong>debugging SPA timing bugs</strong>.</p><p>On SPA projects, the issue is often not that a pageview is missing completely. The issue is that it fires too early or too late.</p><p>Typical case:</p><blockquote><em>URL changed<br>-&gt; soft-navigation detected<br>-&gt; analytics pageview fired<br>-&gt; product/category data updated later</em></blockquote><p>Or the opposite:</p><blockquote><em>route changed<br>-&gt; app renders new content<br>-&gt; data layer updated<br>-&gt; router listener fires again<br>-&gt; duplicate pageview</em></blockquote><p>The third use case is <strong>alignment between tracking and performance measurement</strong>.</p><p><a href="https://developer.chrome.com/blog/final-soft-navigations-origin-trial">One of the main goals of the Soft Navigations API is to make Core Web Vitals measurement possible per SPA navigation, not only for the initial hard page load</a>.</p><p>For tracking, this is useful because analytics pageviews and performance context can stop living in two different worlds.</p><p>Ideally, we can connect:</p><blockquote><em>analytics pageview<br>soft navigation id<br>performance entries<br>user interaction</em></blockquote><p>That can help explain not only which page the user visited, but also which user-visible transition was slow, broken or measured incorrectly.</p><p>The practical value is not in having another browser feature. The value is better quality control for SPA tracking:</p><blockquote><em>Did we track what the user actually experienced as navigation?</em></blockquote><h3>Where to be careful</h3><p>The first limitation is <strong>browser support</strong>.</p><p><a href="https://developer.chrome.com/docs/web-platform/soft-navigations-experiment">At this stage, Soft Navigations API should not be treated as a universal production baseline for all users</a>. It is still an experimental Chrome feature in an origin trial, and not all users will support it, especially older Chrome versions and other browsers.</p><p>The second limitation is that <strong>browser signal is not the same as business definition</strong>.</p><p>The browser can detect a soft navigation, but that does not automatically mean this navigation should become an analytics pageview. Checkout steps, PDP variant changes, overlay routes and filtered search results can be defined differently in different tracking specs.</p><blockquote><em>soft-navigation detected<br>does not automatically mean<br>analytics pageview must be sent</em></blockquote><p>The third limitation is <strong>duplicate risk</strong>.</p><p>If a site already has router-based virtual pageviews, adding a new listener without control can create a second source of pageviews.</p><blockquote><em>router listener sends virtual_page_view<br>soft-navigation listener sends virtual_page_view<br>result: duplicate pageviews</em></blockquote><p>The fourth limitation is <strong>data layer timing</strong>.</p><p>A soft navigation can be detected before the application has updated all business context. Before sending a pageview, the implementation still needs to check whether required fields are ready.</p><blockquote><em>soft-navigation detected<br>-&gt; pageview fired<br>-&gt; data layer updated later<br>-&gt; stale or incomplete payload</em></blockquote><p>The fifth limitation is <strong>consent and privacy logic</strong>.</p><p>Soft Navigations API can help with detection, but it does not solve consent. If the pageview or diagnostic event is sent to an analytics destination, it must follow the same consent logic as other tracking calls.</p><p>The safest starting point is:</p><blockquote><em>Use Soft Navigations API for diagnostics first.<br>Use it as a production trigger only after controlled testing.</em></blockquote><p>So the first step is not “replace router tracking”. The first step is to check where browser-detected navigations match or disagree with the current analytics implementation.</p><h3>Conclusion</h3><p>Soft Navigations API does not solve SPA tracking completely. But it adds a useful missing layer: a browser-level signal that a user went through a page-like transition without a full page reload.</p><p>For tracking teams, this is useful not as a replacement for router listeners, data layer or tracking specs. It is useful as another control point.</p><p>The main idea is simple:</p><blockquote><em>virtual_pageview should not only mean “the route changed”<br>it should mean “the user experienced a meaningful page-like transition”</em></blockquote><p>In SPA, this difference matters.</p><p>A route can change without a real content change.<br>Content can change before the data layer is updated.<br>An analytics pageview can fire before the business context is correct.<br>One user transition can accidentally become two or three pageviews.</p><p>Soft Navigations API does not remove these problems automatically. But it helps us see them from another angle: not only from the application router or tag manager, but also from the browser.</p><p>My practical takeaway:</p><blockquote><em>Use it first as a diagnostic and validation signal.<br>Only then consider it as part of production SPA pageview logic.</em></blockquote><p>That is where I see the real value for web analytics and tracking engineering.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=15a708621f6f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Before Asking AI for Insights, Give It a Contract]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/before-asking-ai-for-insights-give-it-a-contract-a9a53948c06f?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/a9a53948c06f</guid>
            <category><![CDATA[data-quality]]></category>
            <category><![CDATA[web-analytics]]></category>
            <category><![CDATA[datalayer]]></category>
            <category><![CDATA[web-tracking]]></category>
            <category><![CDATA[data-contract]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Wed, 18 Mar 2026 06:25:17 GMT</pubDate>
            <atom:updated>2026-03-18T06:55:18.368Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7I_P5524_zBV69FjkcP0MQ.png" /></figure><p><strong>TL;DR:</strong> I built <a href="https://github.com/dgizdevans/ga4-datalayer-as-code"><strong>ga4-datalayer-as-code</strong></a> because AI in analytics is only as reliable as the tracking baseline behind it.</p><p>If you plug an LLM into raw events, inconsistent naming, and loosely defined ecommerce payloads, it will still produce answers, but too often by guessing business logic from noise. The point of DataLayer as Code is not “more documentation.” It is to turn tracking into a strict, machine-readable contract: one baseline for developers, analysts, QA, and AI. Without that layer, AI does not reduce ambiguity , it scales it.</p><h3>Why AI in analytics does not reduce chaos without a strict tracking baseline — it scales it</h3><p>Everyone wants the same thing right now: connect AI to analytics and get insights faster.</p><p>At first glance, that sounds reasonable. If we already have events, tables, a data layer, a warehouse, and dashboards, why not let a model look across all of it and help us find patterns?</p><p>Because in most cases, the model is not connected to a system. It is connected to a noisy, partially inconsistent trace of that system.</p><p>AI does not understand your tracking layer by default. It does not know which event is canonical, which one is legacy, which parameter is required, which field silently stopped populating three months ago, or why two similar-looking events exist at the same time. It sees raw names and values and tries to infer meaning from a structure that is often only loosely defined.</p><p>That is why AI in analytics without a strict baseline does not create reliability. It scales ambiguity.</p><h3>The problem is not AI. The problem is the input layer.</h3><p>Most real-world tracking setups do not exist as one strict, formalized system.</p><p>They are usually a mix of frontend code, GTM logic, old documentation, unwritten assumptions, one-off fixes, legacy event names, and ecommerce implementations that drifted across teams and releases.</p><p>Humans can tolerate that better than models can. A human analyst may know that purchase_v2 should be ignored, that value excludes tax in one flow but not in another, or that one parameter is still present only because nobody cleaned it up after a migration. A person can ask a teammate, search an old ticket, or reconstruct intent from context.</p><p>A model cannot do that in any reliable way. It does not know which parts of the tracking layer are canonical, which are historical leftovers, and which are simply wrong. It will still generate an interpretation. It just may be wrong in a very confident way.</p><p>So the question is not whether the model is smart. The question is whether the layer underneath your analytics is defined well enough to be interpreted consistently.</p><h3>What DataLayer as Code actually means</h3><p>DataLayer as Code is not “YAML for the sake of YAML.”</p><p>It only becomes useful when the tracking layer is treated as a formal contract.</p><p>That means there is one versioned, reviewable, machine-readable baseline that explicitly defines which events exist, which parameters are allowed, which fields are required, which are optional, how ecommerce works, how items are structured, where user context lives, and which field dependencies are considered valid.</p><p>In other words, tracking stops being a collection of assumptions and becomes an interface.</p><p>That distinction matters. Assumptions can be interpreted. An interface is either respected or violated.</p><h3>What a real tracking contract consists of</h3><p>For DataLayer as Code to be more than a slogan, it needs concrete parts.</p><p>First, there needs to be an envelope. That is the baseline payload shape: event, event_id, user_id, user_properties, optional debug fields, and common rules for what a valid event object looks like.</p><p>Second, there needs to be a baseline for web events. Not only manual recommended events, but also auto-collected and enhanced measurement events. Without that layer, both humans and models see an incomplete picture of what the tracking setup actually contains.</p><p>Third, ecommerce needs its own section. This is usually where things fall apart fastest: value, currency, transaction_id, promotion context, product lists, and especially items.</p><p>Fourth, ecommerce needs a shared item schema. Not just “we have an items array,” but an actual structural definition of which fields are allowed, which types they expect, and where item-level custom parameters are permitted.</p><p>Fifth, it needs rules, not just descriptions. If currency is required whenever value is present, that should not live as a comment in a document. It should exist as a validation rule.</p><p>And finally, it needs examples that pass validation against that same contract. Because in practice, developers do not consume abstract schemas first. They consume working examples.</p><p>That is the point where DataLayer as Code starts to become an engineering layer instead of another piece of documentation.</p><h3>The uncomfortable truth: for many teams, this is still overhead</h3><p>This part matters.</p><p>For a lot of teams, DataLayer as Code can absolutely become overhead.</p><p>If there is no validation, no CI, no QA usage, no runtime checks, and no change process built around the contract, then DLaC can easily turn into just another artifact sitting next to Confluence.</p><p>In that state, it does not solve much.</p><p>So simply converting tracking documentation into YAML or JSON Schema is not the win. The win starts when the contract becomes the source of truth.</p><p>That is the real difference.</p><p>Not another document. One baseline that frontend developers, analysts, QA, and AI systems all read from. One place where event names, parameter rules, ecommerce structure, and allowed payload shapes are defined consistently.</p><p>That removes the classic conflict: the product spec says one thing, GTM contains another, and the actual data layer does something else.</p><p>If the source of truth is fragmented, any automation built on top of it inherits that fragmentation. If the source of truth is formalized, ambiguity narrows.</p><h3>Why this matters even more for AI</h3><p>For humans, weak formalization is inconvenient. For AI, it is a structural input problem.</p><p>LLMs can sound convincing even when they are operating on ambiguous semantics. That is what makes this dangerous. The model will not say, “Your tracking layer has no strict contract, so I refuse to reason about it.” It will reason anyway.</p><p>It just has to guess far more than most teams realize.</p><p>It does not know which events are canonical and which are legacy. It does not know whether value means order value, product revenue, or something inconsistently calculated across flows. It does not know whether price is a string, a number, a formatted display value, a unit price, or a tax-inclusive price unless the contract says so.</p><p>This is where DataLayer as Code becomes more than documentation for the team. It becomes an instruction layer for the model.</p><p>The contract gives the model not just the data, but the rules for interpreting the data.</p><p>Without that, AI is not analyzing your tracking system. It is inferring how that system might work from incomplete evidence.</p><h3>A simple ecommerce example</h3><p>Take a typical ecommerce sequence: add_to_cart, begin_checkout, purchase, items, price, value, currency, and transaction_id.</p><p>If a model only sees raw payloads, several things immediately become ambiguous.</p><p>Is price a number or a string? Is it a unit price or a line total? Does it include tax? Is value item revenue, order revenue, or a mixed implementation that changed over time? Is transaction_id always required or only required on the final purchase event? Are unknown fields inside items valid extensions or just implementation mistakes?</p><p>Without a contract, the model has to infer all of that.</p><p>Here is a valid purchase payload with a clear structure:</p><pre>{<br>  &quot;event&quot;: &quot;purchase&quot;,<br>  &quot;user_id&quot;: &quot;crm_12345&quot;,<br>  &quot;user_properties&quot;: {<br>    &quot;account_type&quot;: &quot;b2b&quot;,<br>    &quot;user_tier&quot;: &quot;pro&quot;<br>  },<br>  &quot;page_location&quot;: &quot;https://example.com/checkout/success&quot;,<br>  &quot;page_title&quot;: &quot;Order Complete&quot;,<br>  &quot;transaction_id&quot;: &quot;ORD-2026-0001&quot;,<br>  &quot;currency&quot;: &quot;EUR&quot;,<br>  &quot;value&quot;: 129.99,<br>  &quot;shipping&quot;: 4.99,<br>  &quot;tax&quot;: 21.49,<br>  &quot;coupon&quot;: &quot;SPRING10&quot;,<br>  &quot;customer_type&quot;: &quot;new&quot;,<br>  &quot;items&quot;: [<br>    {<br>      &quot;item_id&quot;: &quot;sku_1&quot;,<br>      &quot;item_name&quot;: &quot;Pro Plan&quot;,<br>      &quot;item_brand&quot;: &quot;Example&quot;,<br>      &quot;item_category&quot;: &quot;Subscription&quot;,<br>      &quot;price&quot;: 129.99,<br>      &quot;quantity&quot;: 1<br>    }<br>  ]<br>}</pre><p>Now compare that with a payload that looks plausible, but is semantically messy:</p><pre>{<br>  &quot;event&quot;: &quot;purchase&quot;,<br>  &quot;transactionID&quot;: &quot;ORD-2026-0001&quot;,<br>  &quot;value&quot;: &quot;129.99 EUR&quot;,<br>  &quot;items&quot;: [<br>    {<br>      &quot;name&quot;: &quot;Pro Plan&quot;,<br>      &quot;price&quot;: &quot;129.99 incl tax&quot;,<br>      &quot;qty&quot;: &quot;1&quot;<br>    }<br>  ]<br>}</pre><p>A human might still understand what the second payload was trying to do. A model might also generate a reasonable interpretation. But neither has a formal basis for saying whether it is valid or invalid unless the contract exists.</p><p>With a contract, the ambiguity collapses.</p><p>The model can know that transaction_id is required, not transactionID. It can know that value must be numeric and that currency is required when value is present. It can know that items must follow a shared schema, that price is numeric, and that undeclared top-level fields are not acceptable.</p><p>That is a very different operating condition.</p><h3>What this baseline actually gives you</h3><p>It reduces ambiguity.</p><p>Not because it magically makes tracking perfect, but because it narrows the room for interpretation.</p><p>It makes the analytics layer less dependent on institutional memory. It gives QA a formal definition of what a valid payload looks like. It gives developers a real interface instead of scattered examples and tribal knowledge. And it gives AI not just raw event data, but the structural rules needed to interpret that data more reliably.</p><p>That last point matters more than most teams think.</p><p>Humans can often recover missing semantics from context. Models compensate for missing semantics by guessing.</p><p>That is why AI on top of weak tracking often feels impressive at first and unreliable later. The language is good. The baseline is not.</p><h3>What DataLayer as Code does not solve</h3><p>It is important to stay honest here.</p><p>DataLayer as Code does not fix poor ownership. It does not replace business understanding. It does not magically clean up a bad tracking setup. It does not make AI “smart.” And it absolutely does not guarantee useful insights on its own.</p><p>It solves a narrower problem.</p><p>It makes the input layer more formal and less ambiguous.</p><p>That is not a silver bullet. But it is a necessary technical layer if you want anything downstream — analytics, QA, governance, or AI — to operate on something more stable than accumulated assumptions.</p><h3>The main point</h3><p>DataLayer as Code is not valuable because it looks more “engineered.”</p><p>And it is not valuable because YAML or JSON Schema are fashionable.</p><p>It is only valuable when it becomes a formal baseline.</p><p>As long as tracking remains a mix of documentation, assumptions, and partial implementations, AI will do what it does best in that environment: confidently infer meaning where the system itself never defined the rules clearly.</p><p>So before asking AI for insights, give it a contract.</p><p>Otherwise, you are not scaling intelligence. You are scaling ambiguity.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a9a53948c06f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Profiling and Flattening GA4 Data in BigQuery: A Step-by-Step Walkthrough]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/profiling-and-flattening-ga4-data-in-bigquery-a-step-by-step-walkthrough-46d7f9e629a5?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/46d7f9e629a5</guid>
            <category><![CDATA[analytics-engineering]]></category>
            <category><![CDATA[bigquery]]></category>
            <category><![CDATA[ga4]]></category>
            <category><![CDATA[sql]]></category>
            <category><![CDATA[web-analytics]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Mon, 16 Feb 2026 08:04:20 GMT</pubDate>
            <atom:updated>2026-02-16T19:58:21.003Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*RBIsUlAQcsTJWVXJ" /><figcaption>Photo by <a href="https://unsplash.com/@zoshuacolah?utm_source=medium&amp;utm_medium=referral">Zoshua Colah</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p><strong>TL;DR</strong>: I profile GA4 BigQuery export (event_params, user_properties, items), exclude empty/sparse fields, and build a reproducible event-level flat table (1:1 with source events), validated by row count, date range, and event distribution.</p><p>GA4 exports data to BigQuery in nested/repeated structures — event_params, user_properties, items. Inside BigQuery this is a powerful and convenient model. But as soon as you need to work with this data outside BigQuery - pandas, ML pipelines, BI tools - nested arrays become a serious problem. Most tools expect flat tables, and writing UNNEST logic in every query is tedious and error-prone.</p><p>In this article I’ll walk through my approach: first profile the data (understand what’s there, what’s empty, what’s broken), then build a flattening query based on the profiling results. Every query can be run directly in the BigQuery console — no Python required.</p><p>The dataset is the public bigquery-public-data.ga4_obfuscated_sample_ecommerce (Google Merchandise Store, Nov 2020 - Jan 2021, 92 daily tables, ~4.3M events). This is a standard GA4 ecommerce export - the specific keys and fill rates will differ in your case, but the approach generalizes to most GA4 exports.</p><h3>What’s Inside a GA4 BigQuery Export</h3><p>Each row is one event. The schema splits into two types of fields:</p><p><strong>Flat fields</strong> (accessible via dot notation, no UNNEST needed): event_date, event_name, event_timestamp, user_pseudo_id, device.*, geo.*, traffic_source.*, ecommerce.*, privacy_info.*, stream_id, platform.</p><p><strong>Nested/repeated fields</strong> (require UNNEST):</p><ul><li>event_params - ARRAY&lt;STRUCT&lt;key, value&gt;&gt; - event parameters</li><li>user_properties - same structure</li><li>items - product array (ecommerce)</li></ul><p>The nested fields are what cause problems outside BigQuery. Our goal is to turn them into columns.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E8wwxHSrhxa9u9JxjvARlA.png" /><figcaption>GA4 BigQuery export schema: nested arrays event_params, user_properties, items</figcaption></figure><h3>Profiling Strategy</h3><p>Before writing a flattening query, you need to understand the data. The naive approach — “unnest everything” — produces a table full of junk columns, empty fields, and unexpected data types.</p><p>The approach: profile each group of fields, make data-driven decisions, and only then build the query.</p><p>Plan:</p><ol><li>event_params - key coverage, NULL rates, type inconsistencies</li><li>user_properties - presence and sparsity</li><li>items - presence, data quality</li><li>Flat fields — find completely empty fields</li><li>Flattening query — based on results</li><li>Validation — verify nothing was lost</li></ol><blockquote><strong>Cost note:</strong> scanning events_* costs money. I start with a single day table (events_20210131) for fast, cheap profiling, and only run full scans when confirming specific suspicious findings - filtered with WHERE ep.key IN (...) to minimize bytes processed.</blockquote><h3>1. Profiling event_params</h3><p>Strategy: profile on a single table first (events_20210131) - cheaper to scan and faster to run. Then confirm suspicious findings with a full scan across all tables (events_*).</p><h4>1.1 Unique keys</h4><p>Starting with a single table:</p><pre>SELECT DISTINCT ep.key<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`,<br>UNNEST(event_params) AS ep<br>ORDER BY 1;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Fv6Zc2Egt-QcOD4E7uadmQ.png" /><figcaption>Query result</figcaption></figure><blockquote>Result: 28 unique event_params keys in a single day.</blockquote><h4>1.2 Value types and fill rate per key</h4><p>Each event_param stores its value in one of four slots: string_value, int_value, float_value, double_value. We need to understand which key uses which slot and whether any keys are completely empty:</p><pre>SELECT<br>    ep.key,<br>    COUNT(*) AS total,<br>    COUNTIF(ep.value.string_value IS NOT NULL) AS string_filled,<br>    COUNTIF(ep.value.int_value IS NOT NULL) AS int_filled,<br>    COUNTIF(ep.value.float_value IS NOT NULL) AS float_filled,<br>    COUNTIF(ep.value.double_value IS NOT NULL) AS double_filled,<br>    COUNTIF(<br>        ep.value.string_value IS NULL<br>        AND ep.value.int_value IS NULL<br>        AND ep.value.float_value IS NULL<br>        AND ep.value.double_value IS NULL<br>    ) AS all_null<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`,<br>UNNEST(event_params) AS ep<br>GROUP BY ep.key<br>ORDER BY ep.key;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IMcBM5Jje3eVSxnUqnPqHg.png" /><figcaption>event_params key coverage and value type distribution</figcaption></figure><blockquote>Result:</blockquote><blockquote>4 keys are 100% NULL: all_data, dclid, gclid, gclsrc</blockquote><blockquote>session_engaged - mixed type (string + int)</blockquote><blockquote>Remaining keys use a single type consistently</blockquote><h4>1.3 Confirming across all 92 tables</h4><p>A single day isn’t enough — we confirm across the full dataset. We filter only the suspicious keys to avoid scanning everything:</p><pre>SELECT<br>    ep.key,<br>    COUNT(*) AS total,<br>    COUNTIF(<br>        ep.value.string_value IS NULL<br>        AND ep.value.int_value IS NULL<br>        AND ep.value.float_value IS NULL<br>        AND ep.value.double_value IS NULL<br>    ) AS all_null<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*`,<br>UNNEST(event_params) AS ep<br>WHERE ep.key IN (&#39;all_data&#39;, &#39;dclid&#39;, &#39;gclid&#39;, &#39;gclsrc&#39;)<br>GROUP BY ep.key;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/909/1*rBeLVDcLXZNjIx3QEPr5bA.png" /><figcaption>all_data, dclid, gclid, gclsrc — 100% NULL across all tables (full dataset scan)</figcaption></figure><p>Confirmed: total = all_null for all four. Safe to exclude.</p><h4>1.4 Mixed type: session_engaged</h4><p>Investigating the problematic key separately:</p><pre>SELECT<br>    ep.value.string_value,<br>    ep.value.int_value,<br>    COUNT(*) AS cnt<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`,<br>UNNEST(event_params) AS ep<br>WHERE ep.key = &#39;session_engaged&#39;<br>GROUP BY 1, 2<br>ORDER BY cnt DESC;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/747/1*z5S5H5Xm63_m2H3XOOEHbw.png" /><figcaption>session_engaged distribution — mixed storage type: string (“1”,”0&quot;) and int (1) values.</figcaption></figure><p>session_engaged is a binary flag (0/1), but GA4 stores it inconsistently: some values in string_value, others in int_value. This is a known GA4 export quirk. Handled at flattening with:</p><pre>COALESCE(value.string_value, CAST(value.int_value AS STRING))</pre><blockquote><strong>event_params summary</strong></blockquote><blockquote>28 unique keys</blockquote><blockquote>4 excluded (100% NULL): all_data, dclid, gclid, gclsrc</blockquote><blockquote>1 with mixed type: session_engaged - COALESCE</blockquote><blockquote><strong>24 keys retained</strong> for flattening</blockquote><h3>2. Profiling user_properties</h3><h4>2.1 Single day check</h4><pre>SELECT up.key, COUNT(*) AS total<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`,<br>UNNEST(user_properties) AS up<br>GROUP BY up.key;</pre><blockquote>Result: empty — zero records for this particular day. Let’s check the full dataset.</blockquote><h4>2.2 Full scan</h4><pre>SELECT COUNT(*) AS total_kv_pairs<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*`,<br>UNNEST(user_properties) AS up;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/257/1*hKBuT8IPwMnxB9WQH2V7Zg.png" /></figure><p>136 key-value pairs across 4.3 million events. Practically unused.</p><blockquote><strong>user_properties summary: </strong>Not included in the flat table — too sparse to justify creating columns.</blockquote><h3>3. Profiling items</h3><h4>3.1 Field fill rates</h4><pre>SELECT<br>    COUNT(*) AS total_items,<br>    COUNTIF(item.item_id IS NOT NULL) AS item_id_filled,<br>    COUNTIF(item.item_name IS NOT NULL) AS item_name_filled,<br>    COUNTIF(item.item_brand IS NOT NULL) AS item_brand_filled,<br>    COUNTIF(item.price IS NOT NULL) AS price_filled,<br>    COUNTIF(item.quantity IS NOT NULL) AS quantity_filled,<br>    COUNTIF(item.item_revenue IS NOT NULL) AS item_revenue_filled,<br>    COUNTIF(item.coupon IS NOT NULL) AS coupon_filled<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`,<br>UNNEST(items) AS item;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QHx0YkjatJ4XIn6j2_sc-w.png" /><figcaption>Items field fill rates (single-day sample)</figcaption></figure><p>3.2 Items per event by event type</p><pre>SELECT<br>    event_name,<br>    COUNT(*) AS events,<br>    SUM(ARRAY_LENGTH(items)) AS total_items,<br>    ROUND(AVG(ARRAY_LENGTH(items)), 1) AS avg_items_per_event<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`<br>WHERE ARRAY_LENGTH(items) &gt; 0<br>GROUP BY 1<br>ORDER BY 2 DESC;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/714/1*UEyU1RiT-36buyfhA4N2Tg.png" /><figcaption>Items per event by event_name</figcaption></figure><p>Dataset-specific modeling quirk: view_item, add_to_cart, select_item contain ~10 items per event, when logically there should be one. In this dataset, these events record the entire product list on the page, not just the selected item.</p><h4>3.3 Sparsity of quantity and item_revenue (full scan)</h4><pre>SELECT<br>    COUNT(*) AS total_items,<br>    COUNTIF(item.quantity IS NOT NULL) AS quantity_filled,<br>    COUNTIF(item.item_revenue IS NOT NULL) AS revenue_filled<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*`,<br>UNNEST(items) AS item;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/539/1*ZHLYANDDPlxbF1hncKB_yQ.png" /></figure><p>quantity is filled in 3.8% of rows, item_revenue in 0.4%. Both only on purchase events.</p><blockquote><strong>items summary: </strong>Not included in the flat event-level table. Our goal is one row = one event, and CROSS JOIN UNNEST on items would break that granularity. On top of that, there’s a dataset-specific modeling quirk in this dataset. If item-level analysis is needed, items are better handled as a separate table joined by event_timestamp + user_pseudo_id.</blockquote><h3>4. Profiling flat fields</h3><h4>4.1 NULL check — single day</h4><p>Checking fields that may be empty in this dataset:</p><pre>SELECT<br>    COUNT(*) AS total,<br>    COUNTIF(event_previous_timestamp IS NOT NULL) AS event_prev_ts,<br>    COUNTIF(event_server_timestamp_offset IS NOT NULL) AS event_server_ts_offset,<br>    COUNTIF(user_id IS NOT NULL) AS user_id,<br>    COUNTIF(event_value_in_usd IS NOT NULL) AS event_value_usd,<br>    COUNTIF(privacy_info.analytics_storage IS NOT NULL) AS privacy_analytics,<br>    COUNTIF(privacy_info.ads_storage IS NOT NULL) AS privacy_ads,<br>    COUNTIF(privacy_info.uses_transient_token IS NOT NULL) AS privacy_transient,<br>    COUNTIF(device.mobile_os_hardware_model IS NOT NULL) AS device_hw_model,<br>    COUNTIF(device.vendor_id IS NOT NULL) AS device_vendor_id,<br>    COUNTIF(device.advertising_id IS NOT NULL) AS device_ad_id,<br>    COUNTIF(ecommerce.refund_value_in_usd IS NOT NULL) AS ecom_refund_usd,<br>    COUNTIF(ecommerce.refund_value IS NOT NULL) AS ecom_refund,<br>    COUNTIF(ecommerce.shipping_value_in_usd IS NOT NULL) AS ecom_ship_usd,<br>    COUNTIF(ecommerce.shipping_value IS NOT NULL) AS ecom_ship<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pnjkn9B760X4C0iBk84mUw.png" /><figcaption>Single-day NULL check for selected flat fields</figcaption></figure><p>12 fields with zero fill on a single day. event_value_in_usd is also 0 - but may be populated on other days. Requires a full scan.</p><h4>4.2 Confirming across all tables</h4><pre>SELECT<br>    COUNT(*) AS total,<br>    COUNTIF(event_previous_timestamp IS NOT NULL) AS event_prev_ts,<br>    COUNTIF(event_server_timestamp_offset IS NOT NULL) AS event_server_ts_offset,<br>    COUNTIF(user_id IS NOT NULL) AS user_id,<br>    COUNTIF(event_value_in_usd IS NOT NULL) AS event_value_usd,<br>    COUNTIF(privacy_info.analytics_storage IS NOT NULL) AS privacy_analytics,<br>    COUNTIF(privacy_info.ads_storage IS NOT NULL) AS privacy_ads,<br>    COUNTIF(device.mobile_os_hardware_model IS NOT NULL) AS device_hw_model,<br>    COUNTIF(device.vendor_id IS NOT NULL) AS device_vendor_id,<br>    COUNTIF(device.advertising_id IS NOT NULL) AS device_ad_id,<br>    COUNTIF(ecommerce.refund_value_in_usd IS NOT NULL) AS ecom_refund_usd,<br>    COUNTIF(ecommerce.refund_value IS NOT NULL) AS ecom_refund,<br>    COUNTIF(ecommerce.shipping_value_in_usd IS NOT NULL) AS ecom_ship_usd,<br>    COUNTIF(ecommerce.shipping_value IS NOT NULL) AS ecom_ship<br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*`;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Fdde_4CBYVNhrKSE_j3EoA.png" /><figcaption>Full-dataset NULL check — 12 fields confirmed 100% empty across all tables</figcaption></figure><p>Confirmed: 12 fields are 100% NULL across the entire dataset. event_value_in_usd has 5,242 filled rows (0.12%) - retained.</p><blockquote><strong>Flat fields summary: </strong>12 fields not included in the flat table (100% NULL):</blockquote><blockquote>event_previous_timestamp, event_server_timestamp_offset, user_id</blockquote><blockquote>privacy_info.analytics_storage, privacy_info.ads_storage</blockquote><blockquote>device.mobile_os_hardware_model, device.vendor_id, device.advertising_id</blockquote><blockquote>ecommerce.refund_value_in_usd, ecommerce.refund_value, ecommerce.shipping_value_in_usd, ecommerce.shipping_value</blockquote><p><strong>Note</strong>: collected_traffic_source does not exist in this dataset - this field was added to the GA4 BigQuery export after 2021.</p><h4>Profiling Summary</h4><p><strong>Not included in the flat table:</strong></p><ul><li>event_params: 4 keys (100% NULL) - all_data, dclid, gclid, gclsrc</li><li>user_properties: not flattened into columns (136 pairs across 4.3M events)</li><li>items: not included (keeps event-level granularity, dataset-specific modeling quirk)</li><li>Flat fields: 12 (100% NULL)</li></ul><p><strong>Retained:</strong></p><ul><li>24 event_params keys (1 with mixed type: session_engaged - COALESCE)</li><li>All remaining flat fields</li></ul><h4>5. Flattening Query</h4><p>Based on the profiling results, we build the final query. Each event_param is extracted via a scalar subquery wrapped in MAX() - a defensive coding pattern that guards against the case where the same key appears twice in a single event. In GA4, keys are typically unique per event, but if a duplicate key appears, MAX() ensures the subquery still returns a single value instead of failing with &quot;scalar subquery produced more than one element&quot;:</p><pre>SELECT<br>    -- identifiers<br>    event_date,<br>    event_name,<br>    event_timestamp,<br>    event_bundle_sequence_id,<br>    event_value_in_usd,<br>    user_pseudo_id,<br>    user_first_touch_timestamp,<br>    stream_id,<br>    platform,<br><br>    -- privacy<br>    privacy_info.uses_transient_token,<br><br>    -- device<br>    device.category AS device_category,<br>    device.mobile_brand_name AS device_mobile_brand,<br>    device.mobile_model_name AS device_mobile_model,<br>    device.mobile_marketing_name AS device_mobile_marketing,<br>    device.operating_system AS device_os,<br>    device.operating_system_version AS device_os_version,<br>    device.language AS device_language,<br>    device.is_limited_ad_tracking AS device_limited_ad_tracking,<br>    device.web_info.browser AS browser,<br>    device.web_info.browser_version AS browser_version,<br><br>    -- geo<br>    geo.continent,<br>    geo.country,<br>    geo.region,<br>    geo.city,<br>    geo.sub_continent,<br>    geo.metro,<br><br>    -- traffic_source (first touch attribution)<br>    traffic_source.source AS traffic_source,<br>    traffic_source.medium AS traffic_medium,<br>    traffic_source.name AS traffic_campaign,<br><br>    -- ecommerce<br>    ecommerce.total_item_quantity AS ecom_total_item_qty,<br>    ecommerce.purchase_revenue_in_usd AS ecom_revenue_usd,<br>    ecommerce.purchase_revenue AS ecom_revenue,<br>    ecommerce.tax_value_in_usd AS ecom_tax_usd,<br>    ecommerce.tax_value AS ecom_tax,<br>    ecommerce.unique_items AS ecom_unique_items,<br>    ecommerce.transaction_id AS ecom_transaction_id,<br><br>    -- event_params (24 keys, pivoted into columns)<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;page_title&#39;) AS page_title,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;page_location&#39;) AS page_location,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;page_referrer&#39;) AS page_referrer,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;source&#39;) AS ep_source,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;medium&#39;) AS ep_medium,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;campaign&#39;) AS ep_campaign,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;term&#39;) AS ep_term,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;ga_session_id&#39;) AS ga_session_id,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;ga_session_number&#39;) AS ga_session_number,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;engagement_time_msec&#39;) AS engagement_time_msec,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;entrances&#39;) AS entrances,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;debug_mode&#39;) AS debug_mode,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;engaged_session_event&#39;) AS engaged_session_event,<br>    (SELECT MAX(COALESCE(value.string_value, CAST(value.int_value AS STRING)))<br>        FROM UNNEST(event_params)<br>        WHERE key = &#39;session_engaged&#39;) AS session_engaged,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;clean_event&#39;) AS clean_event,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;link_domain&#39;) AS link_domain,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;link_url&#39;) AS link_url,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;outbound&#39;) AS outbound,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;percent_scrolled&#39;) AS percent_scrolled,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;search_term&#39;) AS search_term,<br>    (SELECT MAX(value.int_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;unique_search_term&#39;) AS unique_search_term,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;promotion_name&#39;) AS ep_promotion_name,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;coupon&#39;) AS ep_coupon,<br>    (SELECT MAX(value.string_value) FROM UNNEST(event_params)<br>        WHERE key = &#39;currency&#39;) AS ep_currency<br><br>FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*`;</pre><p>In the BigQuery console: run the query with “Save results -&gt; BigQuery table”, specifying the target dataset and table name (e.g. flatten_no_item).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vALMRwJc0BbxS6SRRzX8Nw.png" /><figcaption>Save as BQ table</figcaption></figure><p>Or use DDL:</p><pre>CREATE OR REPLACE TABLE `your-project.your_dataset.flatten_no_item` AS<br>-- paste the SELECT above</pre><h3>6. Validation</h3><h4>6.1 Row count match</h4><pre>SELECT<br>    (SELECT COUNT(*)<br>     FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*`) AS source_events,<br>    (SELECT COUNT(*)<br>     FROM `your-project.your_dataset.flatten_no_item`) AS flat_events;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/343/1*gOE9h8RKZdHKKUCrO94bzg.png" /><figcaption>Validation check: source vs flattened table row count (1:1 match)</figcaption></figure><p>Should match 1:1. If it doesn’t — an UNNEST somewhere created duplication (our query has no UNNEST, only scalar subqueries, so the risk is effectively zero).</p><h4>6.2 Date range</h4><pre>SELECT<br>    MIN(event_date) AS date_from,<br>    MAX(event_date) AS date_to,<br>    COUNT(DISTINCT event_date) AS unique_dates<br>FROM `your-project.your_dataset.flatten_no_item`;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/577/1*Ekyuq2-ozJPFr8nu6gOSbQ.png" /><figcaption>Validation check: date range and number of unique event dates</figcaption></figure><h4>6.3 Event distribution</h4><pre>SELECT event_name, COUNT(*) AS events<br>FROM `your-project.your_dataset.flatten_no_item`<br>GROUP BY 1<br>ORDER BY 2 DESC;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/518/1*7BQAc6xlRu9AaGDevuSUHA.png" /><figcaption>Validation check: event distribution by event_name</figcaption></figure><p>All three checks passed: 4,295,584 rows, 92 days, 17 event types, 60 columns. The flat table fully matches the source data.</p><h3>What’s Next</h3><p>The flat table is ready for pandas, BI tools, dbt models — no nested structures, no UNNEST.</p><p>A few notes for adapting this to your own data:</p><ul><li><strong>Your event_params keys will be different.</strong> Steps 1.1–1.2 will reveal your key set. Profile empty keys and mixed types the same way.</li><li><strong>collected_traffic_source</strong> - if your data is from after 2021, this field exists and contains session-scoped UTM parameters. Profile it separately.</li><li><strong>user_properties</strong> - may be substantially populated in your project. Decide whether to include based on fill rate.</li><li><strong>items</strong> - if you need item-level granularity, build a separate table with CROSS JOIN UNNEST and JOIN by event_timestamp + user_pseudo_id.</li></ul><h3>Final Result &amp; Resources</h3><p>You can find the full flattened dataset and all the source code used in this walkthrough here:</p><p><strong>Dataset on Hugging Face: </strong><a href="https://huggingface.co/datasets/gizdevans/ga4-bq-flattened-data">GA4 BigQuery Flattened Dataset</a> — Ready-to-use CSV for your analysis.<br><strong>GitHub Repository: </strong><a href="https://github.com/dgizdevans/ga4-bq-flatten/tree/main">dgizdevans/ga4-bq-flatten</a> — SQL scripts and export workflows.</p><p>Feel free to use these resources for your own projects or as a starting point for more advanced GA4 data modeling!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=46d7f9e629a5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Case study: why Safari GA4 cohorts show “Day 0 purchases”, and what server-side GTM can actually…]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/case-study-why-safari-ga4-cohorts-show-day-0-purchases-and-what-server-side-gtm-can-actually-50659ba51637?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/50659ba51637</guid>
            <category><![CDATA[marketing-analytics]]></category>
            <category><![CDATA[serverside-tracking]]></category>
            <category><![CDATA[bigquery]]></category>
            <category><![CDATA[ga4]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Sat, 31 Jan 2026 13:49:31 GMT</pubDate>
            <atom:updated>2026-01-31T13:49:31.082Z</atom:updated>
            <content:encoded><![CDATA[<h3>Case study: why Safari GA4 cohorts show “Day 0 purchases”, and what server-side GTM can actually fix</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Jq5gzuRkGGY71GQF" /><figcaption>Photo by <a href="https://unsplash.com/@rupixen?utm_source=medium&amp;utm_medium=referral">rupixen</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>➤ TL;DR: This is usually not “Safari users convert instantly”. It is ID churn. In GA4 BigQuery cohorts, user_pseudo_id depends on a stable client_id. In Apple Safari, client_id is more likely to reset, so returning users look new and purchases collapse into Day 0. The only class of fixes is making the identifier as first-party and as server-managed as possible (for example via FPID in sGTM). Permanent stability without login is not achievable.</p><p><strong>Context<br></strong>GA4 on a commerce site, server-side Google Tag Manager is in place. Safari is a large share of traffic. Cohort analysis in BigQuery by user_pseudo_id shows an anomaly: in Safari, 80%+ of purchases land on Day 0. In Google Chrome, delayed conversions show up as expected. Numbers here are rounded and adjusted.</p><p><strong>What is actually happening<br></strong>For GA4 web, user_pseudo_id in BigQuery is effectively sustained by the GA client identifier (practically, the value stored in _ga / client_id). If client_id does not survive to the next visit:</p><ul><li>returning users become “new”</li><li>cohorts rebuild incorrectly</li><li>a purchase that should appear on D2/D7 gets counted as D0 of a new cohort</li></ul><p>Safari triggers this more often due to tracking prevention and stricter storage behavior. Server-side setups can make it worse if the tagging endpoint is not truly first-party, or if cookies are set inconsistently.</p><p><strong>Common technical causes (especially with sGTM)</strong></p><ol><li>The sGTM endpoint is not truly first-party<br>Typical symptoms: tagging runs on a separate domain, extra redirects, cross-domain hops, or an endpoint that looks like a third-party service. Result: cookies are set, but do not live as expected, or they live in a different context.</li><li>Cookie attributes are wrong or inconsistent<br>Wrong Domain/Path, missing Secure, wrong SameSite, too-short Max-Age/Expires, or mixed client-set vs server-set logic. Result: the ID changes more frequently than in Chrome.</li><li>Client-side and server-side identifiers drift<br>Even if _ga exists, the server side does not always receive it reliably (blocked requests, inconsistent endpoints, partial delivery of headers/cookies). Result: part of traffic is measured with a fresh client_id.</li></ol><p><strong>What can be done with server-side GTM</strong></p><p>➤ <strong>Approach 1</strong>, truly first-party endpoint for sGTM<br>Serve the server container from a first-party subdomain (for example https://tag.example.com) and keep it “in-family” with minimal redirects and no unnecessary domain switching.<br>This does not guarantee cookie persistence in Safari, but it removes self-inflicted third-party-like behavior and typically reduces churn.</p><p>➤ <strong>Approach 2</strong>, FPID in sGTM, server-managed stable ID and mapping into GA4</p><p>For GA4 with sGTM, the standard pattern is FPID (First-Party ID). In practice, sGTM stores a stable identifier in a first-party HttpOnly cookie and uses it as the foundation for the client_id forwarded to GA4. This is the “server-managed ID” setup where JS-managed _ga becomes less critical because the identifier is controlled server-side.<br>Critical points: correct cookie attributes (Domain/Path/Secure/SameSite/Max-Age), a single endpoint, and a single read/write logic so multiple “truths” for the ID are not created.</p><p>Limits:</p><ul><li>Safari can still cap lifetime even for server-set cookies if behavior is classified as tracking, so “fix forever” without login is not realistic</li><li>private mode, cookie cleanup, ad blockers, anti-tracking extensions will keep breaking persistence</li><li>consent and privacy compliance still apply, long-lived IDs should not be set without a valid basis</li></ul><p>➤<strong>Approach 3</strong>, user_id (login) as the only stable cohort anchor</p><p>If the product supports authentication, the most stable way to measure delayed conversions is to cohort on user_id (or an internal account ID), using GA4 identifiers as secondary.<br>This only covers logged-in share and still needs careful design to avoid PII leakage.</p><p><strong>What matters</strong></p><ul><li>“80% of purchases on Day 0” usually means identifier churn, not that Safari has no delayed conversions.</li><li>sGTM helps only if the identifier becomes truly first-party and server-managed (for example via FPID).</li><li>Even with server-set cookies, Safari can limit lifetime, so the only truly stable anchor is user_id (login), if available.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=50659ba51637" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Universal Commerce Protocol (UCP): what you can track, and what’s not there]]></title>
            <link>https://medium.com/@dmitrijs.gizdevans/universal-commerce-protocol-ucp-what-you-can-track-and-whats-not-there-2b957d1f6f3f?source=rss-2f006587f959------2</link>
            <guid isPermaLink="false">https://medium.com/p/2b957d1f6f3f</guid>
            <category><![CDATA[agentic-commerce]]></category>
            <category><![CDATA[web-analytics]]></category>
            <category><![CDATA[ecommerce]]></category>
            <category><![CDATA[ecommerce-tracking]]></category>
            <dc:creator><![CDATA[Dmitrijs Gizdevans]]></dc:creator>
            <pubDate>Sat, 24 Jan 2026 09:32:37 GMT</pubDate>
            <atom:updated>2026-01-24T09:32:37.376Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hTUElJD7GfPft_fJwaM5bw.png" /></figure><p>➤ <strong>TL;DR:</strong> This post looks at UCP from an e-commerce tracking angle. UCP gives you a server-to-server checkout session and order lifecycle, not UI click events. So you do not get classic client-side funnel events like view_item, add_to_cart, begin_checkout “from inside the platform UI”. What you do get is reliable server-side measurability of checkout steps and post-purchase states. And depending on the integration, client-side tracking may appear if your own web checkout is actually shown to the user.</p><p><strong>Context</strong></p><p>We keep exploring a new environment for e-commerce analytics: purchases happening inside LLM interfaces. It’s a different type of channel where the UI often lives outside the merchant site, so the usual client-side events either do not exist, or only appear in specific cases when you deliberately create a return point to your domain.</p><p>Previously, I looked at how Instant Checkout works in the OpenAI ecosystem. The analytics takeaway was straightforward: measurement is mostly server-side, and the client-side funnel inside the assistant UI is largely unavailable.</p><p>The next logical step is to look at what Google offers. Universal Commerce Protocol (UCP) is presented as a universal protocol for agentic commerce and a way to standardize checkout integrations between a platform and a merchant. I’m not interested in protocol details for their own sake. The practical question is: what signals does UCP actually provide for e-commerce tracking, where does funnel observability stop, and when do you get any chance of client-side measurement.</p><p>Below I break down UCP in the same format as before: how the flow works, what you can measure reliably server-side, which UI events you do not get out of the box, and how to plug this channel into a standard e-commerce event model.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/680/1*twOXZwR1ud0R-aQlVe1C9A.png" /><figcaption>Co-developed and adopted by industry leaders</figcaption></figure><p><strong>How UCP works (approach-level, not a how-to)</strong></p><p>UCP defines “capabilities”, one of the core ones is Checkout Capability. In the REST binding, this becomes a set of operations around a checkout session: create, get, update, complete, cancel.</p><p>Typical shape:</p><ol><li>POST /checkout-sessions - create a checkout session</li><li>GET /checkout-sessions/{id} - fetch current state</li><li>PUT /checkout-sessions/{id} - update (replace-whole-object model, you send full state, not a patch)</li><li>POST /checkout-sessions/{id}/complete - complete and place the order</li><li>POST /checkout-sessions/{id}/cancel - cancel the session</li></ol><p>Discovery uses /.well-known/ucp, so a platform can discover base endpoints and service version.</p><p>There are also transport requirements that matter for data quality and tracking reliability: Request-Signature, Idempotency-Key, Request-Id, and the expected behavior when an idempotency key is reused with different content (409 Conflict).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/412/0*4HNye7RqmhBQgen-.png" /><figcaption>See it in action: Checkout</figcaption></figure><p><strong>Main takeaway for tracking: UCP is not about UI events</strong></p><p>UCP describes state and operations, but it does not give you “user clicked the button” as a first-class event. In practice:</p><ul><li>You can build a reliable server-side event model from checkout session operations and order states.</li><li>You do not get view_item / select_item / add_to_cart as UI events out of the box. The closest surrogate is comparing line_items between session states. That is a proxy, not a click.</li></ul><p>Separately, in Google’s UCP implementation as an example of a UCP platform, complete maps to “Place Order”. Once that call is received, payment processing starts. The request includes a payment token and risk signals. From a tracking point of view, that’s a strong server-side “user reached the end” signal.</p><p><strong>Measurability vs attribution</strong></p><p>It helps to separate two concepts:</p><ul><li><strong>Measurability:</strong> checkout steps and order state changes can be measured server-side because you have deterministic operations and a final order truth.</li><li><strong>Attribution:</strong> traffic source, user behavior inside the platform UI, reasons for purchase, this depends on whether the platform provides referral or placement metadata. UCP itself does not define GA-style attribution, it’s out of scope.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/412/0*gcDmiJbh7gngLAHB.png" /></figure><p><strong>When client-side tracking appears in UCP</strong></p><p>This depends on where the checkout UI is rendered.</p><ol><li>Native checkout on the platform side (example: platform UI handoff)<br> The user enters sensitive details in the platform UI. You see server calls and final states. Your JS does not run inside the platform UI, there is no dataLayer there. Result: the funnel is mostly server-side.</li><li>Embedded checkout (your web checkout is actually shown to the user)<br> Google UCP also describes an optional embedded checkout path: your existing web-based checkout is embedded in the host surface via an iframe/webview, with two-way communication (postMessage / JSON-RPC).</li></ol><p><strong>Result:</strong> client-side tracking becomes possible because your frontend is loaded (even if inside an iframe). But part of the flow may still be delegated to the host (for example payment credentials, address collection). That means your UI signals can be mixed: some inside your iframe, some outside your DOM. You should expect a hybrid funnel.</p><p><strong>Server-side tracking: minimal canonical model</strong></p><p>If you already use a server-side pipeline (CDP, event stream, DWH, Adobe server-side ingestion), UCP fits naturally as a separate channel.</p><p>Minimal events:</p><ul><li>checkout_session_created - on POST /checkout-sessions</li><li>checkout_session_updated - on PUT /checkout-sessions/{id}</li><li>checkout_session_completed - on POST /checkout-sessions/{id}/complete (strong “place order” signal)</li><li>order_created / order_updated - as the separate “order truth” layer (post-purchase states like refund, cancel, chargeback if present in your OMS)</li></ul><p>Identifiers:</p><ul><li>primary key: your order_id (your OMS truth)</li><li>correlation: checkout_session_id (UCP session id)</li><li><em>idempotency is mandatory</em> (otherwise retries will create duplicates), and conflicts should be treated as errors (409 in the expected behavior)</li></ul><p>Money:</p><ul><li>In Google UCP examples, amounts are integers in minor units (for example cents).</li><li>Currency is ISO 4217 uppercase (USD).</li></ul><p><em>Example “internal” payload for a purchase event (your event stream format, not UCP):</em></p><pre>{<br>  &quot;event&quot;: &quot;purchase&quot;,<br>  &quot;channel&quot;: &quot;ucp&quot;,<br>  &quot;order_id&quot;: &quot;ORD-10004561&quot;,<br>  &quot;checkout_session_id&quot;: &quot;chk_1234567890&quot;,<br>  &quot;currency&quot;: &quot;USD&quot;,<br>  &quot;totals&quot;: {<br>    &quot;subtotal_minor&quot;: 10000,<br>    &quot;tax_minor&quot;: 850,<br>    &quot;shipping_minor&quot;: 500,<br>    &quot;total_minor&quot;: 11350<br>  },<br>  &quot;items&quot;: [<br>    { &quot;id&quot;: &quot;product_12345&quot;, &quot;quantity&quot;: 1, &quot;price_minor&quot;: 10000 }<br>  ],<br>  &quot;timestamps&quot;: {<br>    &quot;completed_at&quot;: &quot;2026-01-24T10:30:00Z&quot;<br>  }<br>}</pre><p><strong>Data quality and security (this impacts tracking directly)</strong></p><ul><li>Request signing (Request-Signature) and request tracing (Request-Id) are not “legal stuff”. They are the baseline that prevents your event stream from being polluted and helps you stitch retries, errors, and duplicates correctly.</li><li>Idempotency-Key is the protocol-level foundation for deduplication, and it’s also a useful input for analytics dedup rules.</li><li>For embedded checkout, you are in an iframe + postMessage world. You must validate origin, enforce CSP frame-ancestors, and be realistic about what client-side identifiers will be stable in that environment.</li></ul><p><strong>Conclusion</strong></p><p>UCP gives you a strong, deterministic server-side foundation to measure checkout progress and order outcomes, but UI-level ecommerce events in the GA4 sense are not part of the protocol. For classic client-side ecom tracking, the deciding factor is where the UI lives. If it’s platform UI, you’re almost entirely server-side. If it’s embedded web checkout, client-side signals become possible, but some steps may still be delegated to the host, so the funnel becomes hybrid.</p><p><strong>Links</strong></p><ul><li><a href="https://developers.google.com/pay/api/universal-commerce-protocol/overview?utm_source=chatgpt.com">https://developers.google.com/pay/api/universal-commerce-protocol/overview</a></li><li><a href="https://ucp.dev/specification/checkout-rest/?utm_source=chatgpt.com">https://ucp.dev/specification/checkout-rest/</a></li><li><a href="https://developers.google.com/merchant/ucp/guides/checkout/native?utm_source=chatgpt.com">https://developers.google.com/merchant/ucp/guides/checkout/native</a></li><li><a href="https://developers.google.com/merchant/ucp/guides/checkout/embedded?utm_source=chatgpt.com">https://developers.google.com/merchant/ucp/guides/checkout/embedded</a></li><li><a href="https://developers.google.com/merchant/ucp/guides/order-lifecycle">https://developers.google.com/merchant/ucp/guides/order-lifecycle</a></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/349/1*J1QOrQhm_8v61L84XLaOeA.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2b957d1f6f3f" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>