Skip to content

UTM Tracking Inventory

What It Does

The UTM tracking inventory shows which UTM tracking combinations are defined in the Easy8 source code. It helps product owners and developers understand:

  • which product areas and user actions are tracked;
  • which plugin owns the tracking;
  • what a particular UTM combination is intended to measure;
  • which plugins currently have no detectable UTM tracking.

The inventory is not an analytics report. It does not show how often an action was used or confirm that users triggered it. It only reports tracking that the scanner can find in the source code.

Running the Scanner

The modification_easysoftware plugin must be present because it contains the generated inventory used by the page. Run the scanner from the root of a worktree:

ruby .opencode/scripts/generate_utm_inventory.rb

The scanner searches supported Ruby and frontend source files, collects detectable UTM campaign, content, and term combinations, removes duplicates, and updates the generated inventory file.

Review the generated diff after running the command. The generated JSON must not be edited manually; corrections should be made in the source tracking or scanner instead.

If modification_easysoftware or its inventory target directory is not present, the command prints a warning and exits successfully without creating files.

Descriptions

Tracking declarations can include an optional plain-language description. Descriptions should explain the specific action and its entry point, for example:

// utm-inventory-description: Creates a product backlog item from the product backlog board action.

Use a description only when the surrounding code makes the tracked behavior reasonably clear. Generic helpers and dynamically assembled tracking may cover several different flows; in those cases, leaving the description empty is better than guessing.

The scanner supports these immediately preceding comment forms:

  • // utm-inventory-description: ... in JavaScript and TypeScript;
  • # utm-inventory-description: ... in Ruby;
  • <%# utm-inventory-description: ... %> in ERB views.

Viewing the Inventory

Administrators can open /utm_tracking_inventory to view the generated inventory. The page provides filters for plugin, campaign, content, and term. Lower-level filter choices automatically follow the selected higher-level values.

Entries without a reliable source description are shown as Not available.

Scanner Limitations

The scanner works from source code and can reliably include only values it can determine without running the application. Dynamic values, uncommon tracking patterns, and indirectly assembled parameters may be missing. Conversely, commented-out or unusually structured code can occasionally be detected incorrectly.

Treat the inventory as a useful overview rather than a guarantee of complete runtime coverage. When adding or changing a UTM campaign, also follow the UTM tracking standard and coordinate the export whitelist addition where required.