LocallyticsEvents

Retrieve analytics for custom events tracked with locallyticsCapture.

Usage

import { LocallyticsEvents } from "locallytics";

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

console.log(events);
// {
//   totalEvents: 456,
//   uniqueSessions: 123,
//   topEvents: [
//     { event: "button_click", count: 234 },
//     { event: "form_submit", count: 123 },
//     ...
//   ],
//   dailyStats: [
//     { date: "2024-01-15", events: 45 },
//     { date: "2024-01-16", events: 52 },
//     ...
//   ]
// }

Signature

LocallyticsEvents(
  databaseUrl: string,
  range: DateRange,
  format?: DataFormat
): Promise<EventAnalytics | string>

Parameter	Type	Required	Default	Description
`databaseUrl`	`string`	Yes	-	Database connection URL
`range`	`DateRange`	Yes	-	Time range to query
`format`	`DataFormat`	No	`"json"`	Output format (json or csv)

DateRange

"last24h" — Last 24 hours
"last7d" — Last 7 days
"last30d" — Last 30 days

Return Type

When format is "json" (default):

interface EventAnalytics {
  totalEvents: number;
  uniqueSessions: number;
  topEvents: Array<{ event: string; count: number }>;
  dailyStats: Array<{ date: string; events: number }>;
}

Examples

Last 24 Hours

const today = await LocallyticsEvents(
  process.env.DATABASE_URL,
  "last24h"
);

CSV Export

const csv = await LocallyticsEvents(
  process.env.DATABASE_URL,
  "last30d",
  "csv"
);

// Save to file
await fs.writeFile("events.csv", csv);

Dashboard Component

app/dashboard/page.tsx

import { LocallyticsEvents } from "locallytics";

export default async function EventsDashboard() {
  const events = await LocallyticsEvents(
    process.env.DATABASE_URL,
    "last7d"
  );

  return (
    <div>
      <h1>Event Analytics</h1>
      <p>Total Events: {events.totalEvents}</p>
      <p>Unique Sessions: {events.uniqueSessions}</p>

      <h2>Top Events</h2>
      <ul>
        {events.topEvents.map(({ event, count }) => (
          <li key={event}>{event}: {count}</li>
        ))}
      </ul>
    </div>
  );
}

Top Events

The topEvents array returns the 10 most frequent events, sorted by count:

[
  { event: "button_click", count: 234 },
  { event: "form_submit", count: 123 },
  { event: "video_play", count: 89 },
  // ... up to 10 events
]

Daily Stats

The dailyStats array shows event counts per day:

[
  { date: "2024-01-15", events: 45 },
  { date: "2024-01-16", events: 52 },
  { date: "2024-01-17", events: 38 }
]

Dates are in YYYY-MM-DD format, ordered chronologically.

locallyticsCapture — Track custom events
LocallyticsData — Query pageview analytics

LocallyticsEvents

On this page