eventlens-js

Browser analytics SDK for EventLens. Drop it in with a <script> tag or install via npm — auto-captures page views, clicks, form submits, errors, and page leave out of the box.

Installation

npm install eventlens-js

Or via CDN (IIFE bundle):

<script src="https://unpkg.com/eventlens-js/dist/eventlens.iife.js"></script>

Quick Start

Script tag

<script src="https://unpkg.com/eventlens-js/dist/eventlens.iife.js"></script>
<script>
  const el = new EventLens({ apiKey: "el_your_api_key" });
</script>

npm / ESM

import EventLens from "eventlens-js";

const el = new EventLens({ apiKey: "el_your_api_key" });

That's it. Auto-capture starts immediately.

Configuration

const el = new EventLens({
  apiKey: "el_your_api_key",        // required — find this in your EventLens project settings
  endpoint: "https://your-server",  // optional — defaults to http://localhost:8080
  autoCapture: {                    // optional — all true by default
    pageViews: true,
    buttons: true,
    links: true,
    forms: true,
    errors: true,
    pageLeave: true,
  },
});

// Disable all auto-capture
const el = new EventLens({ apiKey: "el_xxx", autoCapture: false });

API

identify(userId)

Associate a user with all subsequent events.

el.identify("user_123");

Call this after login. All events tracked after this point will carry the user_id.

track(eventName, metadata?)

Manually track a business event.

el.track("upgrade_clicked", { plan: "pro", source: "banner" });
el.track("video_played", { video_id: "abc123", duration_sec: 142 });

destroy()

Remove all auto-capture listeners and restore patched history methods. Call on logout if you need a clean teardown.

el.destroy();

maskSensitive(value) (utility)

Mask PII patterns (email, phone, card number, SSN) in a string before passing it to track(). Not applied automatically — use it when your metadata includes user-entered values from form fields.

import { maskSensitive } from "eventlens-js";

el.track("search", { query: maskSensitive(searchInput.value) });
// "[email protected]" → "[email]"
// "4111 1111 1111 1111" → "[card]"

Auto-Captured Events

| Event | Trigger | Key metadata | |---|---|---| | session_start | SDK initialised | user_agent, language | | page_view | Page load + SPA navigation | path, title, referrer | | button_click | <button> clicked | element_type, element_id, text | | link_click | <a> clicked | element_type, element_id, text, href | | click | [data-eventlens] clicked | element_type, element_id, text | | form_submit | <form> submitted | element_type, element_id, action | | page_leave | Tab hidden / closed | path, duration_ms | | error | Uncaught JS error | message, source, line, column |

Explicit capture with data-eventlens

Mark any element for capture without writing JS:

<div data-eventlens="open_chat">Chat with us</div>

This fires a click event with element_id: "open_chat".

Usage in React

Initialise once outside any component:

// src/analytics.ts
import EventLens from "eventlens-js";

export const analytics = new EventLens({ apiKey: "el_your_api_key" });

Identify after auth resolves:

import { analytics } from "@/analytics";

analytics.identify(user.id);

Track business events anywhere:

analytics.track("checkout_started", { cart_total: 99.99 });

Page views on React Router navigation are captured automatically — no extra setup needed.

License

MIT