Dashboard-managed tracking rules

Find out whether visitors click a call to action, submit a form, or reach a key section. After installing the optional rules SDK once, an owner or admin can configure supported interactions from the dashboard without another code change for each rule.

The module fetches the enabled rules when it starts, installs bounded listeners, and emits an event when a rule matches. New tracker starts and page loads pick up changes; open tabs keep their loaded catalog. Reuse stable selectors so later rule edits do not require a site rebuild. A form-submit event records an attempt, not a confirmed signup.

The ELI5 version

A rule says:

1. Where? Use a stable tracking attribute, ID, class, CSS selector, text, or XPath.
2. When? Watch click, double-click, mouse, submit, keyboard, or first-visible behavior.
3. What? Emit a stable event name.
4. Only here? Optionally limit it to one relative page path.
5. Bring anything? Optionally read up to ten small properties from other elements.

That is it. No séance with a tag manager required.

Selector and event options

Supported selector types are id, class, css, text, and xpath. Text matching is normalized and bounded; XPath and broad text scans have result limits so one ambitious rule does not adopt the main thread.

Supported interaction events include:

• click, dblclick, mousedown, and mouseup
• submit, change, focus, and blur
• keydown, keyup, and keypress
• play and ended on native audio/video elements
• view, which uses one shared IntersectionObserver and records the first match

Keyboard rules can emit on Enter, Escape, period, or Space. They can also wait until the target reaches a configured character count, or debounce until typing has stopped for a configured number of seconds. The SDK caps a debounce at 60 seconds and clears timers during stop().

Stable targets in React, Vue, and other frameworks

Choose Tracking attribute (recommended) and enter a meaningful name such as pricing. Add the same value to the actual HTML element in your application:

<section data-owleye-track="pricing">…</section>
<button data-owleye-track="signup">Start free</button>

OwlEye saves this as a standard CSS selector, [data-owleye-track="pricing"], so it also works with the existing rules SDK. Names use up to 120 letters, numbers, colons, underscores, or hyphens, starting with a letter or number. Use the same name on repeated items only when you intend to track all of them.

React refs are references inside your component, not selectable HTML attributes. Build-generated CSS classes and generated IDs are not a reliable tracking contract. Your explicit data-* value stays stable when those change. A custom component must forward the attribute to its DOM element:

function PricingSection(props) {
  return <section {...props}>…</section>;
}
<PricingSection data-owleye-track="pricing" />;

Adding a tracking attribute requires one application update. Later rule edits reuse that target without another application build. If you cannot edit markup, use an existing stable ID or semantic CSS selector; text selectors can break when copy or language changes. OwlEye does not guess new selectors after a redesign.

Scroll to a section and common presets

Scroll to section / element records the first time a matching element intersects the viewport. Select a tracking attribute, ID, or CSS selector to target the section. It observes visibility; it does not scroll the page and does not require a scroll gesture. A section visible on initial load counts too. Each element counts once per page navigation; a framework remount creates a new element and can count again. Dynamically inserted sections are discovered automatically.

The editor includes presets for CTA clicks, section views, form submissions, field changes, and links with the download attribute. Replace example target names with those used by your app. A download-link click does not confirm a completed download, and a form submit event does not confirm a successful signup or payment. Track confirmed outcomes with explicit application events.

change listens to a committed native field change, not every keystroke or React’s synthetic onChange callback. Field values remain excluded unless explicitly added as custom properties. Media rules require native audio/video elements; cross-origin embedded players need their own player integration. Use the current SDK for the full interaction set.

Page scope and custom properties

page_path is optional. When present it is an exact relative pathname beginning with /, such as /pricing. Without it, the rule can match on every page.

A rule can define up to ten custom properties. Each property has a key, selector, and selector type. By default, the SDK reads an element’s primitive value when available, otherwise its trimmed textContent; an explicit text-content source reads text instead. A missing element is omitted. Captured strings are bounded to 512 characters. The synchronous enrichRule callback can supply computed primitive fields within the same ten-field limit. Configured captures take precedence, and excess enrichment fields are omitted. Invalid enrichment never suppresses the base event.

Browser setup

Rule tracking is a separate, tree-shakeable SDK entrypoint:

import { trackRules } from "@owleye/analytics/rules";

const rules = trackRules("your-tracking-id");

// During application teardown:
rules.stop();

The SDK fetches enabled rules from GET /v1/rules?site_id={trackingId} without browser credentials. It uses delegated DOM listeners where possible, aborts an in-flight fetch on teardown, and does not store a rule identity in cookies or browser storage.

Management API

GET    /v1/sites/{siteId}/rules
POST   /v1/sites/{siteId}/rules
GET    /v1/sites/{siteId}/rules/{ruleId}
PUT    /v1/sites/{siteId}/rules/{ruleId}
DELETE /v1/sites/{siteId}/rules/{ruleId}

App members can read the rule set. Creating, updating, pausing, or deleting rules requires owner or admin access. The list response includes the rule’s retained-event count, last-fired timestamp and activity in the last 24 hours. Demo rules are readable but immutable.

Rule health and charts

Rules show their last recorded activity within retained history. An enabled rule with no events in the last 24 hours, but activity in the preceding six days, displays a warning in the Console. This can help spot broken selectors after a deployment; it is not a scheduled email or Slack alert and cannot distinguish a broken rule from a quiet site.

Choose Chart this rule to open a Pro View draft for that rule and app. Preview or edit it before saving. Rules collect only after activation; they cannot recover interactions from before they were enabled.

Privacy and performance boundaries

• Rule events use the normal cookie-free ingestion path.
• Sampling is applied per match without planting a stable browser sampling ID.
• Optional captured text and custom properties should be treated as data collection decisions. Choose selectors that avoid names, email addresses, tokens, and free-form sensitive input.
• The SDK keeps listeners, observers, weak element references, and timers bounded and releases them when stopped.

Using script tags

See CDN tracking examples for script tags, campaign attributes, global JavaScript controllers, and manual custom data.