Data & Decisions
Write an Analytics Tracking Plan Before Events Reach Production
Agree on event triggers, authoritative producers, properties and identity before instrumentation ships. A completed registration plan and executed local checks expose duplicate-producer and payload-shape gaps without claiming production validation.
Write an analytics tracking plan as an implementation agreement: define the business question, exact trigger, authoritative producer, required properties, event identity and validation evidence for each event. For every trigger, also name the states and repeat actions that must not create that event. A list of names cannot tell an engineer whether a button click, accepted request or committed account creation is the fact being measured.
Before events reach production, test representative payloads and the trigger paths that can create omissions or duplicates. This LandOffer.ai guide includes a completed fictional registration specification and an executed local event model. No browser, analytics SDK, collector, account registration or production destination was accessed or changed.

Start with the decision the events should support
Snowplow's tracking-design guidance connects business decisions with tracking plans, event specifications and associated data structures. It also emphasizes ownership, explicit triggers and consistent naming. Use those distinctions to describe the event before choosing its implementation syntax.
For this guide's entirely fictional FolioNest application, product analyst Esha wants to distinguish registration-page exposure, valid submissions, server-declared failures and committed account creation. Engineer Mateo owns the client instrumentation; engineer Lin owns the server outcome events. Esha owns the interpretation and acceptance record.
The question is not merely “What is our conversion rate?” First agree what each step means and which population it describes. A person can open several pages, make several attempts or receive a result after leaving the page. Keep views, attempts and accounts as distinct counting units until the metric specification defines how they relate.
This worked example does not estimate real conversion. Its traces are deliberately selected test cases, not sampled user behavior. The plan supports reviewing event meaning and duplicates; a production metric would additionally need an agreed cohort, time window, identity rules, exclusions and data-quality review.
Complete an event specification for one flow
Esha, Mateo and Lin agree on four event names with consistent past-tense actions. These names and the following field rules are authored choices, not a required vocabulary for every analytics product.
| Event | Trigger and explicit non-trigger | Authoritative producer | Required event-specific properties |
|---|---|---|---|
| Registration Viewed | Registration screen becomes visible for a new view; not every component rerender | Client, Mateo | view_id; entry_point is direct or invite |
| Registration Submitted | Client validation passes and the application accepts the attempt for dispatch; not a click blocked by validation | Client, Mateo | attempt_id; method is password or invite |
| Registration Failed | Server finishes the attempt with a declared unsuccessful result; not a temporary client-side validation hint | Server, Lin | attempt_id; reason_code is request_rejected or temporary_error |
| Account Created | Account creation reaches the application's defined committed-success point; not submission, pending processing or a thank-you-page render | Server, Lin | attempt_id; creation_id identifies the business creation |
Every event also requires event_id, event_name, source, occurred_at, schema_version and flow_id. In this local plan, all are nonempty strings except schema_version, which must be the integer one. occurred_at must contain a timezone offset. Event-specific enums and producer restrictions are part of the specification, rather than explanatory notes someone might overlook.
Use the common fields to answer different questions about grouping, attempts, business outcomes and delivery identity. flow_id groups a registration flow; attempt_id identifies one submitted attempt; creation_id identifies the successful business result. event_id identifies an event instance. Retrying delivery of that same instance preserves its event ID, while a genuinely new submission receives a new attempt and event identity.
The plan disallows unlisted payload fields, including raw email, passwords and unstructured error text. Only synthetic tokens appear in the example. This property policy is not proof that all allowed values, SDK context or identifiers are anonymous. The actual collection, consent, access and retention arrangements need their own authorized review.
Twilio Segment's Track specification separates a named event from its descriptive properties. Its wire format and SDK syntax are product-specific. FolioNest's table is a business specification, not a ready-to-send Segment or Snowplow payload; Lin must document the mapping to the chosen transport and provider, and Esha must review how it preserves the event definitions. Those mappings are not executed here.
Test payload shape without confusing it with truth
JSON Schema's object reference distinguishes defining properties from requiring them, and describes how additional properties can be restricted. A field can be documented in a schema without being required unless that requirement is actually expressed. Missing, null and the wrong type also need deliberate treatment.
The companion example saves a machine-readable specification and runs a focused Python validator for exactly these field sets, nonempty strings, integer version, offset-bearing timestamp, enums and allowed producers. It is not a general JSON Schema implementation. No schema library or provider validation engine is installed or claimed as tested.
The local negative checks reject a string version of “1,” a missing attempt ID, an unplanned method value and an extra raw-email field containing an invented placeholder. These results establish the stated local checks, not that every possible sensitive value or schema violation is detected. An allowed string could still contain inappropriate content unless other controls constrain it.
A correctly shaped Account Created payload can also describe something that never happened. The validator cannot inspect a real database commit. That is why the plan names the producer and committed-success point, and why trigger tests need to accompany payload tests. Shape validation and semantic evidence are separate obligations.
Read the completed trigger and duplicate record
The actual local exercise ran on October 27, 2026 with Python 3.12.14. It models client validation and a supplied committed-state flag with ordinary Python functions. It uses no network, database, SDK, actual page or real account. Fixed synthetic timestamps support field-format checks, not clock skew, latency or delivery-order validation.
| Test case | Local model input | Observed result and interpretation |
|---|---|---|
| Valid submission, success still pending | Valid client input; supplied committed state is false | Submitted event exists; Account Created is not emitted by the local trigger function |
| Committed success | Supplied committed state changes to true | Server-shaped Account Created emitted with creation C1 and event E3 |
| Delivery retry | Exact copy of E3 delivered again to the local list | Eight raw records in the primary three-flow stream reduce to seven unique event IDs |
| Client validation failure | Invalid input in a separate flow | A view is present; no Submitted event is emitted |
| Server rejection | Valid submitted attempt followed by declared unsuccessful result | Registration Failed exists; no creation event is added for that attempt |
| Fresh attempt in the same flow | New attempt A4 after A2, with a different event ID | Both submitted events remain; flow-level deduplication would lose a legitimate attempt |
| Two producers claim one creation | Client-shaped and server-shaped creation records have different event IDs but the same creation C1 | Event-ID deduplication retains both; producer validation rejects the client record |
The primary three-flow stream has three views, two submissions, one failure and one creation after event-ID deduplication. The later A4 attempt, double-producer pair and negative payloads are separate test inputs and are not included in those stream counts. Those totals describe its selected traces only. They do not establish a conversion percentage, population coverage or the behavior of actual consent-restricted or offline clients.
The double-producer case is the useful failure. A frontend thank-you page and a backend creation handler can each create a differently identified event about the same business fact. Removing exact delivery duplicates would not solve that problem. FolioNest resolves the specification by making the server the sole authoritative producer, while retaining client submission as a different event.
The script's 21 assertions preserve both the duplicate outcome and the corrected producer rule. They also show that a premature server-shaped creation payload passes field validation. Passing the shape check therefore cannot be used as evidence of an actual committed account. The local trigger's supplied boolean is a model input, not an observed transaction.

Record the correction and its remaining implementation gates
Esha completes a review record: retain Registration Submitted on the client, remove the client from Account Created's allowed producers, and assign Lin the committed-success trigger. Mateo owns checks that component rerenders and blocked form clicks do not create extra submissions. No actual instrumentation code is removed or deployed for this article.
The review accepts the local payload and event-model evidence for the cases above. It leaves browser wiring, the actual application commit point, crash recovery, provider mapping, collector delivery, destination transformations and identity behavior unverified. Lin must document what happens if the business operation commits but event publication fails; a correct event table does not by itself close that reliability gap.
The implementation review also needs to distinguish duplicate handling from missing-event handling. Deduplicating identical records cannot recover an event that was never emitted. Generating a new event ID for every transport retry can create extra counts. Reusing one ID for distinct legitimate events can suppress real activity. The producer's identity rule must survive the actual transport path.
For the local deduplication example, an in-memory dictionary retains one record per event ID. It assumes repeated instances have identical payloads. It does not test conflicting payloads under one ID, persistence across restarts, concurrent arrivals or a provider's deduplication window. Those are separate implementation questions, not guarantees from the seven-record result.
Preserve meaning across clocks, context and versions
Twilio Segment's common-field documentation distinguishes message identity and occurrence, sending and receiving timestamps. It also notes that destination support and automatically populated context vary. Review that mapping rather than assuming a field named timestamp has the same meaning everywhere.
FolioNest's occurred_at means when the specified business event occurs. It is not a warehouse arrival timestamp. The actual pipeline would need to retain appropriate receipt information separately and handle late or out-of-order delivery. A delayed creation event must not silently become a different business date merely because it arrived later.
Inspect automatically collected context as well as custom properties. Page URLs, search strings, identifiers and other enrichment may create a collection scope larger than the four-event table suggests. Review the SDK and destination collection scope separately from the custom-property allowlist, including enrichment and access settings. No such account-side inspection is performed here.
Version the plan when event meaning changes. If Account Created later means “verification completed,” that is a different trigger from the current committed-creation point. Do not silently reuse the old definition and combine incompatible counts. Record the changed meaning, implementation owner, affected consumers, transition and validation evidence before the change reaches production.
The same discipline applies to removing an event. Identify who uses it, what replaces its meaning and how historical results remain interpretable. Tracking-plan ownership is ongoing: a new product state, producer or property can make an old accepted plan incomplete even if its original payload examples still validate.
Finish with a reviewable production gate
Before approving instrumentation, attach the filled event table, allowed properties, trigger evidence and duplicate/missing-event decisions. Name what remains untested and who will verify it in the actual application and delivery path. Keep analytics-provider access and production release approval separate from a successful local fixture.
For the next flow, use the specification to explain one real business question and include cases where each event must not fire. LandOffer.ai publishes this as practical analytics reading; take the completed event table, trigger evidence and unresolved delivery or collection questions to their named reviewers. Keep actual production enablement behind its own approval and observed validation.
Sources and Further Reading
- Snowplow: Introduction to tracking design, updated October 26, 2026; body checked October 27, 2026. No Console or tracker was accessed.
- Twilio Segment: Spec, Track, current body checked October 27, 2026; legacy segment.com documentation returned 403 and this official documentation body was used instead.
- JSON Schema: Object, property/required/additional-property sections checked October 27, 2026. Local checks are a focused Python implementation, not a standards-complete validator.
- Twilio Segment: Spec, Common fields, current body checked October 27, 2026. No SDK, transport or destination behavior tested.


