@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.
Install
npm install @reglow/trackInitialized 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.
- 01
Capture
Automatic listeners plus explicit track() calls produce standard events.
- 02
Queue & retry
Batched queues with exponential backoff; data survives offline periods.
- 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.
| Event | Trigger | Key fields |
|---|---|---|
| $page_view | Route enter | page_key · page_version |
| $click | Click on an element with data-track-id | elem_id · elem_type · text · x / y |
| $exposure | Visible ≥ 50% for ≥ 500ms | elem_id · ratio · visible_ms |
| $scroll | Every +10% of scroll depth | depth · depth_px · page_version |
| biz.search | Search submit or result click | query · is_zero_result · clicked_rank · converted |
| biz.favorite | Favorite / like / share / rate | target_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.
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
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))
})<!-- 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>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.
