locallyticsCapture

Track custom events like button clicks, form submissions, video plays, and more.

Usage

React / Next.js:

"use client";
import { locallyticsCapture } from "locallytics/client";

export function SignupButton() {
  return (
    <button onClick={() => {
      locallyticsCapture("button_click", {
        buttonId: "signup",
        page: window.location.pathname
      });
    }}>
      Sign Up
    </button>
  );
}

Vanilla JS:

<script type="module">
  import { locallyticsCapture } from "locallytics/client";

  document.getElementById("signup").addEventListener("click", () => {
    locallyticsCapture("button_click", { buttonId: "signup" });
  });
</script>

Signature

locallyticsCapture(
  eventName: string,
  properties?: Record<string, unknown>,
  options?: GrabberOptions
): void

Parameter	Type	Required	Description
`eventName`	`string`	Yes	Name of the event to track
`properties`	`Record<string, unknown>`	No	Custom event properties
`options`	`GrabberOptions`	No	Endpoint configuration

Examples

Track Button Clicks

locallyticsCapture("button_click", {
  buttonId: "cta-hero",
  page: "/pricing"
});

Track Form Submissions

locallyticsCapture("form_submit", {
  formName: "contact",
  fields: 5,
  success: true
});

Track Video Interactions

locallyticsCapture("video_play", {
  videoId: "intro-2024",
  duration: 120,
  quality: "1080p"
});

Track E-commerce Events

locallyticsCapture("add_to_cart", {
  productId: "abc-123",
  quantity: 2,
  price: 29.99
});

Properties

Properties can be any JSON-serializable data:

Primitives: strings, numbers, booleans, null
Objects: nested objects are supported
Arrays: arrays of primitives or objects

Properties are stored as JSON strings in the database. Very large property objects may impact database size.

What It Tracks

Each event includes:

eventName — The event name you provided
properties — Your custom properties (stored as JSON)
sessionId — Anonymous UUID (same as pageviews)
timestamp — ISO 8601 timestamp

Privacy

Same privacy guarantees as LocallyticsGrabber:

No cookies — Uses localStorage only
Respects DNT — No tracking if Do Not Track is enabled
No PII — Never collects identifying information

Query Event Data

To retrieve event analytics, use LocallyticsEvents:

import { LocallyticsEvents } from "locallytics";

const events = await LocallyticsEvents(
  process.env.DATABASE_URL,
  "last7d"
);

locallyticsCapture

On this page