How the measurement actually got built

before any tool is opened · the output is a list of questions, not a list of events

CambiumPak was six weeks from relaunching its site. Eleven product families, seventeen SKUs, forty-four downloadable documents, a distributor portal, and five interactive tools that had never existed before — a box configurator, a material comparison tool, a right-size calculator licensed from a third party, a recycled-content credit finder, and the portal itself. The comparison tool was billed monthly.

I did not start by opening a tag manager. I started by sitting down with Dana Whitfield, the marketing director, and asking her what she wished she knew and currently did not. Everything downstream is an answer to something she said in that hour.

Four frustrations. I wrote them down as questions rather than as features, because a question survives a tooling change and a feature request does not:

an honest audit before proposing work · half of what people want is already there and free

Before proposing anything I checked what a standard analytics install gives you for nothing, because proposing work that the platform already does is the fastest way to lose credibility in the room. Enhanced measurement was already collecting page views, scrolls, outbound clicks, site search and file downloads. That last one is the interesting case, and it is the one that shows exactly where a default install stops being useful.

Here is the file-download report as it actually arrived, before I built anything. It is not empty. It is worse than empty — it is plausible.

Everything you would want to ask of that table, it cannot answer. You cannot total spec sheets against instructions, because document type only exists inside a filename. You cannot roll up to a product family, because family only exists as three letters in the middle of a string. And the whole thing breaks silently the day someone renames a file — the row simply stops appearing and no error is ever raised.

That right-hand column is the project. It is also, precisely, Dana's four questions — which is how I knew the scope was right rather than invented.

one document · signed off by marketing and IT before build · it is an intake form, not documentation

This is the artifact I care most about and the one most analytics work skips. It is a single document with one row per event, and the leftmost column is the business question. If a row cannot name the decision it informs, it does not get built — which is how you end up with a property that answers questions instead of one that collects everything and answers nothing.

It also names the parameters up front, and that matters more than it looks: a parameter you did not think of on day one is not recoverable on day ninety. You cannot backfill it.

the step people skip · if the push is ad hoc, every later step inherits the mess

Some of this could have been scraped off the DOM. Most of it should not be. Anything read out of markup is a promise the front end never made, and the front end will break it the first time someone reorders a template. So before the vendor wrote a line, I gave them the exact shape of what to push, and it went into the build as a requirement rather than a favour.

// Fired when a document is downloaded, from anywhere on the site.
// Values come from the product record, never from the filename.
window.dataLayer.push({
  event: 'document_download',
  doc_type: 'spec',              // spec | comparison | features | instructions
  product_sku: 'CP-MLR-1208',
  product_family: 'mailer',     // so roll-ups need no lookup table
  source_page: 'family'          // family | compare | portal | search
});

// Fired once, after authentication resolves. Never on page load.
window.dataLayer.push({
  event: 'portal_login',
  customer_type: 'distributor_rep',  // internal | distributor_rep | fulfilment | brand
  account_tier: 'tier_2',
  first_login: false                // true once, ever — activation, not traffic
});

no auto-events, no plugins · every tag specified, built, then tested before the next one starts

Eleven tags, nine variables, seven triggers. Three are worth showing because each solves a different class of problem: mapping a messy input to a clean one, passing structured parameters through, and reading something the page already knows but never told anyone.

First, the one that fixes Dana's forty-four rows. A lookup table maps a filename pattern to a document type. This is the fallback path — the dataLayer contract from step 04 is the primary source — but legacy links, emailed PDFs and links inside the portal do not always go through it, and a fallback that produces a clean value beats a fallback that produces a filename.

Two details in that table are the whole difference between a variable that works and one that rots. The fourth row alternates seven verbs, because the fourth document in each product pack is not always called the same thing — four families assemble, the rest use, handle, fit, wrap, fill or seal, because that is what the product actually asks of the packer. A pattern matching only "assembly" would have silently dropped seven families out of the report.

And the default is unclassified, not empty. An unclassified row is visible in a report and someone investigates it. An empty value looks like nothing happened, and nobody investigates nothing.

Second, the tag itself, passing the parameters through as named fields rather than jamming them into the event name:

The naming rule underneath this is worth stating because it is the single most common way an analytics property becomes unusable: events are things a person did, parameters are the details. The moment you write download_spec_sheet_pdf you have put a parameter into the event name, and you will never be able to total downloads again without a regular expression and an apology.

Third, the one that turned a cross-vendor project into six lines. Portal login segmentation was scoped as backend work with an external development partner — expose the user role through an API, wire it in, timeline in months. Before agreeing to that, I opened the post-login page and read the markup. The role was already there, on the body element, put there by the theme so it could style the navigation.

function() {
  // The portal theme already writes the role onto <body> to style the nav.
  // Read it rather than commissioning an API to tell us what the page knows.
  var m = document.body.className.match(/\brole-([a-z_]+)\b/);
  if (!m) return 'unresolved';   // never '' — an empty value hides itself

  var map = {
    staff: 'internal', rep: 'distributor_rep',
    threepl: 'fulfilment', brand: 'brand'
  };
  return map[m[1]] || 'unmapped_' + m[1];  // a new role shows up named, not as noise
}

The unmapped_ prefix is deliberate. When someone adds a role in eighteen months — and they will, without telling marketing — it appears in the report as unmapped_auditor rather than being quietly folded into a bucket where it corrupts a segment nobody thinks to re-check.

nothing is published on the strength of "the tag went green" · fired ≠ arrived ≠ correct

A tag firing tells you a tag fired. It does not tell you the parameters resolved, and it certainly does not tell you the platform accepted them. Those are three separate claims and I check them separately. Preview mode first — trigger the interaction on staging, then read the resolved values, not the tag list.

Note what the fallback row proves: the lookup table resolved to the same value the dataLayer supplied. Agreement between the primary path and the fallback is a much stronger signal than either one working alone, and it takes no extra effort to check while you are already looking at the pane.

Then Realtime, because preview proves the browser sent something and Realtime proves the platform received and parsed it. Between those two claims sits every consent tool, ad blocker, and dropped parameter I have ever had to debug.

the quiet step that decides whether any of the previous six were worth doing

A parameter that is collected but not registered as a custom dimension is invisible in reporting. The data is arriving, it is in the payload, and it does not appear in a single report or exploration. People discover this months later, register the dimension, and find it populates from that day forward and not one day earlier. Registration is not retroactive. There is no backfill, no support ticket, no recovery.

So this happened on the same day the tags were built, not after the first month of data.

The highlighted row is a real decision, not a checkbox. customer_type is registered at user scope rather than event scope. Event scope would tell you the customer type of the login event; user scope attaches it to everything that person subsequently does in the session. That is the difference between "1,240 logins, 58% distributor reps" and being able to ask which documents distributor reps download — which is the question Dana was actually circling when she said the portal looked busy. One radio button, and it determines whether half the interesting questions are answerable at all.

free-form exploration · rows, columns, one metric, and reading the totals carefully

Once the dimensions were populating I built the report Dana actually asked for: which documents, for which products. A free-form exploration — product family down the side, document type across the top, sessions as the metric. Deliberately sessions rather than event count, for a reason that turns out to matter enormously.

Her question, answered. Spec sheets and instructions dominate. The comparison sheet is the least-downloaded document in every single family, without exception — and the comparison sheet is the one whose entire job is to help somebody decide whether this is the right format. The document built to win the specification decision was the one nobody was finding. That is a navigation problem wearing a content problem's clothes, and it went straight onto the website roadmap.

Then the last column. Because the metric is sessions and sessions de-duplicate, the row cells and the row total say two different things — and the gap between them is a finding nobody asked for.

The cells sum to 3,739. The de-duplicated session total is 1,742. So the average session that downloaded anything took 2.15 of the four sheets — and since no session can take more than four, at least 38% of them provably took more than one. The true figure is certainly higher; 38% is only the floor the arithmetic guarantees, and I quoted the floor rather than the estimate because the floor is the part I can defend.

That is not a documentation preference. It is the four-sheet structure working exactly as designed and being, for the buyer, exactly as painful as it looks: the board grade is on the spec sheet, the warranty term is on the features sheet, the make-up time is on the instructions, and the recycled band is on the comparison sheet. Nobody set out to make a buyer open four PDFs. It is what happens when four documents each have one owner and nobody measures the seam between them.

the last five percent · a report nobody opens has not changed a decision

An exploration is a thing an analyst opens. Dana is not an analyst, and a report that requires me to run it is a report that stops existing the week I am busy. So the last step is the handover: the same queries, standing, behind a login, with a date range and an export — a dashboard she opens on a Monday without asking anyone.

That build is its own story — the API auth, the caching, the query batching — and it is written up separately, with a working version you can click through.