How do you brief a dev team for tracking work?

Rhobin

July 31, 2026

7 min read

Brief a dev team the way you would brief an interface: for each event, the exact name, the moment it fires, the fields with example values, and when in the page load the data exists. Anything you leave to interpretation comes back as shipped code the tag manager cannot repair.

The symptom

The request went into the client's backlog three weeks ago as one line: can you add the data layer for the checkout so we can track purchases properly. It shipped on Thursday, and it is not usable.

The order value arrives with a currency symbol attached, so it is text where a number was needed. Two templates use two spellings of the same key, so one of them reads empty. The event fires again when somebody reloads the receipt. None of it can be repaired in the tag manager, which only works with what the page hands it.

So it goes back into the backlog, and the next slot is two sprints out. The client is asking why the agency needs a third attempt at something that sounded small, and the honest answer is uncomfortable: it was requested, not specified.

Why it happens

Developers are not guessing out of carelessness. They are filling in the parts nobody wrote down, the way someone who never opens the report reasonably would. A tracking request looks like a feature request and behaves like an interface contract, so it fails where contracts fail: names, timing, shape, and what counts as done.

The name gets decided twice

Google's Tag Manager developer documentation treats consistent naming as a requirement rather than a courtesy: "if you set the page category on the signup page using a variable called pageCategory, your product and purchase pages should use the pageCategory variable as well". A brief that names the data but not the exact keys leaves that choice to two developers, on two templates, in two sprints.

Downstream the rule gets stricter. The Analytics Help page on event naming rules states that "event names are case sensitive" and that "my_event and My_Event are distinct events", that names "must start with a letter", and that you may use "only letters, numbers, and underscores. Don't use spaces." A name that is merely close is not a near miss, it is a second event with its own row in the report.

Timing is almost never in the ticket

The same documentation is specific about order of operations: "the data layer must be created before Tag Manager is loaded", above the container code. And values do not travel with the visitor, since "each variable declared within the data layer object will persist only as long as the visitor remains on the current page". A ticket that says what to push, but not when the value has to be there, produces a tag reading a variable filled a fraction of a second too late. In the report that is the same as no tracking.

Consent has its own ordering rule, and it is the one that quietly costs money. Google's consent mode documentation requires a default state set "on every page of your site before any commands that send measurement data", and notes that "by default, no consent mode values are set". What lands is decided by what loads first, a development concern before it is a consent tool setting.

The shape is assumed rather than agreed

Analytics applies limits a brief rarely mentions. The event collection limits page puts 25 parameters on an event, 40 characters on an event name and 100 characters on a parameter value. Google's ecommerce documentation is blunt about why the structure is not a matter of taste: "to ensure data populates properly in reports, follow the format in this document", and it marks the transaction identifier as "required for purchases and refunds". A developer can ship something valid and sensible that lands nowhere useful, because a report built on the documented structure does not populate from one invented on a Tuesday afternoon.

Nobody agreed what done means

The last cause is procedural. The ticket closes when the code is merged, and the agency finds out whether it worked when a report looks wrong weeks later. No acceptance test in the brief, nobody named to verify it, and no line making tracking part of the release rather than something that happens after one.

What good looks like

A usable brief gives each event a short section of its own and answers four questions in the developer's language.

The exact name. Spelled once, used on every template, taken from the platform's documented names where one exists.
The trigger. The user-visible moment it fires, and when it must not: not on a reload, not on a failed payment, not twice when the page re-renders.
The fields. Each one named, typed, marked required or optional, with a realistic example value beside it. A number means a number, no currency symbol.
When the value exists. On the page at load, or after a response, because that decides whether a tag can read it at all.

Then two lines that separate a specification from a wish. The first is the acceptance test, written so a developer can run it without you: this action, on this page, produces this event, with these fields and these values. The second is the exclusion list. Google's guidance on personally identifiable information asks that "no data be passed to Google that Google could use or recognize as personally identifiable information", and names email addresses and phone numbers as examples. A helpful developer pushing the customer's email into the data layer is a problem you created by leaving that line out.

The narrow exception belongs in the brief too. Enhanced conversions "uses a secure one-way hashing algorithm called SHA256 on your first-party customer data", per Google Ads Help, and works only when "the customer data is available when the conversion tag fires". That is a requirement on the page, not a setting in an ad account, and it is usually discovered a sprint too late.

Writing that document is most of what a tracking implementation actually is, and it is where Archon Signal starts: a documented event schema the client's developers can build against, then collection moved server-side so events leave from one controlled place instead of a pile of tags nobody owns. A correct data layer is a floor, though, not a finish line. Events still start in a browser where ad blockers, consent refusals and network failure remove a share of them, which is why a standard browser-side setup consistently misses 15-30% of conversions, and why roughly 95% is the realistic ceiling on what any setup collects. A ceiling, not a promise.

FAQ

Who should write the specification, the agency or the client's developers?

Whoever understands the reports, which is almost always the agency. Developers decide how an event is implemented, not what it is called, because they never see the dashboard it feeds. Where it genuinely depends is the platform: if the client runs a shop platform or a plugin that already emits events, the spec starts as an inventory of what is emitted today.

Our client's dev team has no capacity. What is the smallest brief worth sending?

One event, the one tied to money. One specified purchase or qualified lead event, with its fields and its acceptance test, beats a twelve page document waiting a quarter for a slot. Getting the slot usually depends on the client wanting it, not the agency asking, so put the cost in their terms first.

Can we skip the data layer and trigger on clicks and page URLs instead?

For simple cases yes. A confirmation page URL, or a click on a button with a stable identifier, costs no dev time and is how most setups reasonably start. It stops holding when the interface is dynamic, when a confirmation renders without the address changing, or when the event needs a value the page never displays, such as margin or whether a lead was qualified. The data layer earns its dev time at that boundary.

How do we stop the work breaking at the next release?

Two things in writing, neither of which costs a sprint. The specification lives in the repository beside the code it describes, so the next developer inherits it. And the tracking check joins the release checklist, so it is a condition of shipping rather than an agency chore afterwards. A release is the usual suspect when tracking that worked last quarter stops.

Should the brief contain code?

Examples help, and one realistic value next to each field removes more ambiguity than a paragraph of prose. What it should not do is dictate the implementation. The contract is the name, the trigger, the fields and the test. How the value reaches the page is the dev team's call, and a brief that respects that line gets read rather than skimmed.

If you would rather find out which events a client account is missing before writing the brief, that is where the free tracking audit starts.