@reglow/track · v0.1

Event tracking, from the first line of code

The template ships with @reglow/track: zero runtime dependencies, automatic page views, clicks, exposures and scroll depth, plus business events like search, favorites and ratings. Swap in your own collector any time.

Zero runtime depsSSR-safePrivacy-friendlyBatched delivery

Install

npm install @reglow/track

Initialized in app/plugins/track.client.ts (client only).

A sample collector lives at server/api/v1/analytics/collect.post.ts.

Point serverUrl at your real collector in production.

  1. 01

    Capture

    Automatic listeners plus explicit track() calls produce standard events.

  2. 02

    Queue & retry

    Batched queues with exponential backoff; data survives offline periods.

  3. 03

    Deliver & aggregate

    POST to the collector; reports are built server-side from event codes.

01 / capabilities

Collection capabilities

Automatic tracking is on by default — declare element IDs and you are done.

Automatic behavior tracking

Clicks, exposures and scroll depth work out of the box; add data-track-id where needed.

Batched delivery & retries

Queue-based batching with exponential backoff and offline persistence.

Sessions & users

30-minute sessions by default; identify() binds users to subsequent events.

Privacy-friendly

Input values are never collected; optOut / optIn and sampling are supported.

SSR-safe

Without window, the SDK falls back to an in-memory adapter — imports never throw.

Remote rules

Visual selection rules can be delivered by your backend, with no code changes.

02 / events

Event model

Standard events are sent by the SDK; business events go through track / trackSearch / trackPreference.

EventTriggerKey fields
$page_viewRoute enterpage_key · page_version
$clickClick on an element with data-track-idelem_id · elem_type · text · x / y
$exposureVisible ≥ 50% for ≥ 500mselem_id · ratio · visible_ms
$scrollEvery +10% of scroll depthdepth · depth_px · page_version
biz.searchSearch submit or result clickquery · is_zero_result · clicked_rank · converted
biz.favoriteFavorite / like / share / ratetarget_type · target_id · score

03 / demo

Live demo

Each button calls the SDK; the panel shows the custom events sent in this session.

Add to cart

track(add_to_cart)

Click a search result

trackSearch()

Favorite product

trackPreference(favorite)

Submit rating

trackPreference(rate, 5)

Automatic $page_view / $click / $exposure / $scroll events are visible in the Network panel under /api/v1/analytics/collect.

event logLatest 4

No events yet — trigger one on the left.

04 / integrate

Integration

The template is already wired up; follow these three steps for a new project.

app/plugins/track.client.ts
// app/plugins/track.client.ts
import { createTrack } from '@reglow/track'

export default defineNuxtPlugin((nuxtApp) => {
  const tracker = createTrack({
    appId: 'ffd-web',
    autoPageView: false,
    autoTrack: { click: true, exposure: true, scroll: true }
  })

  nuxtApp.vueApp.use(tracker)

  const router = useRouter()
  tracker.pageView(router.currentRoute.value.fullPath)
  router.afterEach(to => tracker.pageView(to.fullPath))
})
app/pages/example.vue
<!-- Declarative: auto click tracking reads data-track-id -->
<button data-track-id="buy_btn" data-track-type="button">
  Buy now
</button>

<!-- Directive: writes data-track-* then hands off to auto tracking -->
<button v-track="{ id: 'submit_btn', type: 'button' }">
  Submit order
</button>
Business events
const track = useTracker()

track?.track('add_to_cart', { sku: 'RG-2026', price: 299 })

track?.trackSearch('recycled fabric', {
  clickedRank: 1,
  converted: false
})

track?.trackPreference('favorite', {
  targetType: 'product',
  targetId: 1001
})

05 / guidelines

Naming guidelines

Tracking is a long-lived asset. Consistent naming matters more than collecting everything at once.

  • 01

    Name elem_id as module_action, e.g. detail_add_cart — never reuse user-facing copy.

  • 02

    Define dedicated events and properties for key conversions instead of overloading one event.

  • 03

    Tune the exposure threshold by content type: lower for list cards, higher for hero banners.

  • 04

    page_version changes after a redesign; do not mix heatmaps across versions.

  • 05

    Confirm sampling and the collector URL before launch so test traffic never reaches production reports.