A storefront rebuild can preserve the appearance of an analytics dashboard while changing what its events mean. The old site may record an action after a server confirms success; the new site may record it as soon as a button is clicked. Both implementations can use the same event name, yet the before-and-after comparison is no longer valid.
An event taxonomy is a contract about behavior, not simply a spreadsheet of names. It should explain what happened, when the event becomes true, which parameters describe it, and which business decisions rely on it. This guide provides a migration method for preserving that contract through a storefront change.
Begin with the decisions the data supports
Inventory the reports and operational decisions that depend on current events. Which events feed purchase reporting, lead qualification, funnel analysis, campaign optimization, or product experiments? An event that nobody uses may not deserve migration, while a low-volume event may be critical to a high-consequence decision.
For each use, name the owner and the question. “Track engagement” is too vague. “Identify where a customer fails to complete a delivery-option selection” is a more testable purpose. A clear purpose also helps decide whether additional data collection is justified.
Do not copy all existing parameters by default. Some may be obsolete, inconsistently populated, or too detailed for their purpose. A rebuild is an opportunity to remove unnecessary collection while preserving the information that decisions genuinely require.
Define the event’s truth condition
A truth condition states when an event is justified. Clicking submit is not the same as a successful submission. Opening checkout is not the same as completing an order. A purchase should correspond to the defined transaction event, not merely viewing a page that can be reloaded or visited directly.
The contract should include both positive and negative examples. A valid submission produces the success event after confirmation. A rejected submission, network error, or canceled operation does not. These examples are more useful to an implementer than a name such as form_complete without context.
If an existing event has an unclear definition, document the uncertainty before migration. Do not pretend that the new implementation preserves a meaning that was never stable. The appropriate outcome may be a new definition with an explicit comparability break.
Use platform conventions without losing business meaning
Google Analytics provides recommended e-commerce events and associated parameters. Its guidance covers purchase and refund measurement, including transaction and item information. Where those events fit the behavior, use their documented meaning rather than inventing a parallel vocabulary that breaks standard reporting.
Custom events can cover important interactions that are not already represented by collected or recommended events. Google’s naming rules include case sensitivity and restrictions on reserved names and prefixes. A team convention should stay within those rules and remain readable to people outside the implementation team.
A naming convention alone is not the taxonomy. Two well-named events can still be fired at the wrong moment. Conversely, a legacy name may be awkward but have a stable definition that many reports depend on. Evaluate the cost of renaming separately from the need to correct behavior.
Specify parameter meaning and allowed values
For every parameter, record its type, meaning, source, allowed values, and behavior when unknown. Decide whether a missing value is omitted, explicitly represented, or considered a validation failure. Avoid mixing those approaches silently across pages.
For example, page_language should describe the page’s language rather than infer a visitor’s nationality. A product identifier should use a defined identity level rather than alternate between parent product and variant. A value field needs a documented unit and currency context where applicable.
Free-text fields are usually poor analytics dimensions and can accidentally carry personal information. Do not send a customer’s message, email address, or delivery address as an event parameter. Build an allowlist of necessary fields rather than passing an entire form or application object to the tracking layer.
Create a migration mapping
| Existing behavior | New contract decision | Migration consequence |
|---|---|---|
| Same action, same success condition | Preserve event and parameters | Compare after validating collection |
| Same action, corrected success condition | Document a definition change | Mark a break in the time series |
| One broad event covers different actions | Split into defined events | Update reports and consumers |
| Several names describe one action | Consolidate with explicit mapping | Preserve historical interpretation |
| Event has no decision owner | Review necessity before copying | Remove only after checking dependencies |
The mapping should identify dashboard changes, campaign dependencies, and validation cases. A developer finishing the event code does not automatically update the people and systems that consume it.
Test a matrix of paths
Choose representative journeys: a successful purchase, a failed payment, a validation error, a repeated confirmation-page view, a refund where supported, and a user who does not grant analytics consent. Include mobile and desktop layouts if their implementations differ.
For each case, state the expected events, their order where relevant, and the fields that must be absent. Test duplicate delivery paths as well as missing events. If browser and server instrumentation both report the same outcome, their coordination must be intentional.
Google’s e-commerce documentation uses transaction identifiers in purchase and refund measurement. These identifiers should be stable and meaningful for the transaction; a new random value on every page view undermines duplicate handling and reconciliation. Do not assume that an identifier fixes an incorrectly defined trigger.
Compare records before comparing performance
Before interpreting a post-rebuild conversion change, check event coverage, parameter completeness, duplication, and the relationship to the operational order record. A change in measured revenue may reflect a collection defect, a definition change, or a real business change. Those explanations require different actions.
The operational record and analytics report need not match perfectly. Consent, blocked collection, timing, refunds, and reporting definitions can affect the comparison. The goal is to explain the discrepancy and detect unexpected changes, not force two systems with different scopes to produce identical totals.
Use a dated validation sample with known test transactions or approved non-production scenarios. Exclude labeled tests from business conclusions. Record which events were observed in debugging tools and which later appeared in processed reports; those are separate verification stages.
Release and rollback responsibilities
The release plan should name who checks collection immediately after deployment and who reviews processed reporting later. It should also define the response to a serious defect. A broken purchase event may require a measurement fix without rolling back the storefront, while a defect in checkout behavior has a different operational impact.
Keep the old and new contracts with the release record. If a rollback restores the old storefront, verify that the instrumentation and consent behavior roll back consistently. A mixed state can leave the page working while events continue using the wrong definition.
Keep the taxonomy alive
Future features should add or change events through the same contract. Require a purpose, truth condition, parameter definition, examples, and owner. Review changes for downstream consumers before implementation. This makes the taxonomy part of product maintenance rather than a document created only during a rebuild.
Primary references are Google’s e-commerce measurement guide, custom-event guidance, and event naming rules. For a related but distinct problem, read the catalog taxonomy guide. The bilingual identity review explains how page and author identity can remain consistent through the same kind of change.