Analytics

Add one key to a node and that interaction is reported to the page’s analytics. You choose the moments. Nothing is measured unless you say so. Analytics here means what a person did in your experience. Which items they opened, what they clicked, where they stopped. It is separate from platform monitoring, which measures whether the machinery is healthy.

The one key

analytics sits on a node, beside the action it accompanies.

- type: Button
  label: Book now
  action: bookNow
  analytics:
    event: generate_lead
    params:
      item_id: "{{universal_id}}"

Two fields. event is the name that arrives in the analytics tool. params are the values sent with it. {{...}} reads the data already in scope at that node. It is the same binding an action’s values use, so there is nothing new to learn. A node with no analytics block reports nothing. Silence is the default.

Opening a view is an action

A card and its detail view are one instance. Opening the detail view writes view (the public state; legacy spelling defaultState), which is an action like any other. So it takes the same key.

- type: Box
  action:
    type: setValue
    values:
      - key: view
        value: detail
  analytics:
    event: view_item
    params:
      item_id: "{{universal_id}}"
      item_name: "{{title}}"

Clicks, submits and view changes are one mechanism. There is no separate way to report a view, because there is no separate way to open one.

Choosing event names

Use the analytics tool’s own vocabulary where it has a word for what happened. GA4 defines view_item, generate_lead, select_item and others. Those names populate its built-in reports with no setup. Invent a name only when no standard one fits. Prefix it with unoverse_ so it cannot collide with an event the page already fires.

Moment	Name
Somebody views one item in detail	`view_item`
Somebody submits an enquiry form	`generate_lead`
Somebody opens the experience	`unoverse_experience_opened`

Names are yours to choose. The platform holds no list.

Choosing params

Send what answers a question somebody will ask. Leave out anything that only describes the machinery. Match the field names the customer’s own analytics already uses. Their reports and filters are built on those names, so a matching param joins work they have already done. A generic name arrives as a column somebody has to map by hand.

analytics:
  event: view_item
  params:
    item_id: "{{universal_id}}"
    item_name: "{{title}}"
    item_category: "{{object_type}}"

A param that resolves to nothing is dropped. An absent value is absent in the report, never an empty column that reads as data.

What never goes in an event

Three rules, and breaking any of them is a data protection problem rather than a bug. No personal data. No name, email, phone or date of birth. Analytics tools prohibit it, and the property receiving it belongs to your customer. No authored content. Report which item somebody opened. Never report what it said. No typed text. A person’s question or form entry stays out. Both routinely contain personal detail. An enquiry event carries an opaque reference to the record, never the record.

analytics:
  event: generate_lead
  params:
    lead_id: "{{lead_id}}"
    item_id: "{{universal_id}}"

One event per kind of thing

A course, a product and a service are the same moment. Somebody looked at one thing in detail. Give them one event and separate them with a param.

analytics:
  event: view_item
  params:
    item_category: "course"

Splitting them into view_course and view_product fragments the reporting. An analytics tool breaks one event down by param automatically. It cannot recombine two event names into one funnel.

Where events go is not your decision

You declare what happened. The destination is configured per customer, outside rx/. The reason is practical. The same template runs on a customer’s site, in the Unoverse client, and inside an MCP app host. Each has a different destination, or none. A template cannot know which one it is in. Analytics is off unless a customer has been configured. Your declarations sit dormant until then, and cost nothing.

Checking your events

Turn on debug for the channel you are testing. Each event prints as it fires.

[unoverse:analytics] view_item {item_id: "...", item_name: "..."}

Filter the browser console on unoverse:analytics to see only these.

Troubleshooting

Symptom	Fix
No event at all	the node has no `analytics` block, or the interaction runs on a different node than you think
Event fires, params empty	the `{{field}}` name is not in scope at that node: check the field the node’s own binds use
Event fires twice	two nodes declare it, commonly a wrapper and the element inside it
Nothing reaches the analytics tool	the destination is not configured for that channel, which is the default
Params arrive under the wrong names	match the customer’s vocabulary, not a generic one

Components for the node grammar
State for how a view change is a state write
Lifecycle Hooks for fetching data at a moment, which is a different job

Getting Started

Core Concepts

Workflow

The one key

Opening a view is an action

Choosing event names

Choosing params

What never goes in an event

One event per kind of thing

Where events go is not your decision

Checking your events

Troubleshooting

​The one key

​Opening a view is an action

​Choosing event names

​Choosing params

​What never goes in an event

​One event per kind of thing

​Where events go is not your decision

​Checking your events

​Troubleshooting

​Related

The one key

Opening a view is an action

Choosing event names

Choosing params

What never goes in an event

One event per kind of thing

Where events go is not your decision

Checking your events

Troubleshooting

Related