tracking-events-lib

A small library for capturing user actions such as clicks, inputs, and global errors. It is framework-agnostic but works well in React applications.

It also includes resilient event handling: events are stored in localStorage if sending fails, deduplicated, and synchronized across tabs.

Installation

npm install tracking-events-lib

In Frontend

The library will automatically start listening to DOM events and global events such as error, unhandledrejection, and rejectionhandled. It also handles:

• Resilient event sending

  • Stores events in localStorage if sending fails
  • Flushes immediately using navigator.sendBeacon when page is closing
  • Uses fetch with keepalive for normal sending

• Automatic flush

  • beforeunload and pagehide events
  • Periodic flush every 10 seconds if buffer is not empty

• Anti-duplication

  • Prevents sending the same event multiple times within TTL

• Cross-tab support

  • BroadcastChannel ensures events from other tabs are also captured

You can also tag your elements with data-analytics to track specific events:

<button data-analytics='{"scope":"anonimous","feature":"cta_click","subject":"hero_banner"}'>Click me</button>

Custom Events

tracker.trackCustomEvent({
  scope: "homepage",
  feature: "zapay_entry",
  subject: "user_landed",
});

All custom events are automatically converted to snake_case internally.

Event Format

All events follow the new format:

orn:{technology}:{channel}:{feature}:{identity}

Example:

orn:frontend:website:consulta_gravame:anonimous

• orn – Olho no Carro Resource Name, fixed prefix for all internal identifiers
• technology – frontend or backend
• channel – website, app, api, bot
• feature – feature in use, always snake_case (consulta_veiculo_completo, checkout)
• identity – user identity context (anonimous, authenticated)

Using with React

import { useEffect } from "react";
import { initUserTracking } from "tracking-events-lib";

useEffect(() => {
    const tracker = initUserTracking({
      endpoint: "https://gateway.olhonocarro.com.br/hhighway/event", // (hhighway) and (phighway) for homolog for production
      bufferLimit: 5,
      baseSource: "orn:frontend:website"
    });
})

  return <div>Hello World</div>;
}

Full Changelog

https://github.com/olho-no-carro-tecnologia/onc-highway-web-sdk/compare/v0.1.24...v0.1.25