Real-time View
Relevant source files
The following files were used as context for generating this wiki page:
The Real-time View provides a live dashboard of website activity, offering immediate insights into current visitors, their actions, and their origins. It is designed to give website owners a dynamic, up-to-the-minute overview of traffic, including page views, custom events, geographic distribution, and referral sources. The view automatically refreshes with new data, ensuring the information presented is always current.
This feature is composed of several specialized React components that collectively build the real-time dashboard. Data is fetched periodically from a dedicated API endpoint, which in turn queries the database for the most recent event data within a specific time window.
Architecture and Data Flow
The Real-time View's functionality relies on a client-server architecture where the frontend continuously polls the backend for the latest analytics data.
The following diagram illustrates the high-level data flow from data collection to display:
Data Fetching
The frontend initiates data fetching through the useRealtimeQuery hook. This hook queries the /api/realtime/[websiteId] endpoint at a regular interval to get fresh data.
- Polling Interval: The data is refreshed every 10 seconds, as defined by
REALTIME_INTERVAL. - Time Range: The query retrieves data for the last 30 minutes, as defined by
REALTIME_RANGE.
Sources: src/lib/constants.ts:26-27, src/app/(main)/websites/[websiteId]/realtime/RealtimePage.tsx:17
The sequence diagram below shows the interaction between the client and server for fetching real-time data.
Frontend Components
The Real-time View is constructed from a set of modular components, each responsible for displaying a specific piece of information. The main page component, RealtimePage, assembles these individual parts into a cohesive dashboard.
Sources: src/app/(main)/websites/[websiteId]/realtime/RealtimePage.tsx
Component Summary
| Component | Description | Source File |
|---|---|---|
RealtimePage | The main container that orchestrates data fetching and renders all sub-components. | src/app/(main)/websites/[websiteId]/realtime/RealtimePage.tsx |
RealtimeHeader | Displays summary metrics such as the number of current visitors. | src/app/(main)/websites/[websiteId]/realtime/RealtimePage.tsx:31 |
RealtimeChart | A bar chart showing pageviews and visitors over the last 30 minutes. | src/components/metrics/RealtimeChart.tsx |
RealtimeLog | A live feed of all incoming events, including pageviews, sessions, and custom events. | src/app/(main)/websites/[websiteId]/realtime/RealtimeLog.tsx |
RealtimePaths | A list table displaying the most viewed pages in the current time window. | src/app/(main)/websites/[websiteId]/realtime/RealtimePaths.tsx |
RealtimeReferrers | A list table showing the top referral sources. | src/app/(main)/websites/[websiteId]/realtime/RealtimePage.tsx:42 |
RealtimeCountries | A list table of visitor counts by country. | src/app/(main)/websites/[websiteId]/realtime/RealtimePage.tsx:48 |
WorldMap | A visual map highlighting the geographic distribution of visitors. | src/app/(main)/websites/[websiteId]/realtime/RealtimePage.tsx:51 |
RealtimeChart
This component visualizes pageviews and visitors for the last 30 minutes (REALTIME_RANGE). It is built on top of the generic PageviewsChart component.
- Data: It receives
pageviewsandvisitorsseries data. - Time Unit: The data is aggregated by the
minute. - Date Range: The chart's x-axis is fixed to a 30-minute window, ending at the current minute.
- Animation: It includes logic to disable animations when the chart's time window shifts forward to prevent visual glitches, but animates when the data values themselves change.
Sources: src/components/metrics/RealtimeChart.tsx:16-43, src/lib/constants.ts:26
RealtimeLog
The RealtimeLog component provides a detailed, filterable log of user activity. It displays a virtualized list of events for performance.
Key features include:
- Search: Users can search across various event properties like URL, event name, browser, OS, country, and device.
- Filtering: The log can be filtered to show specific types of events.
The following filter options are available:
| Filter ID | Label | Description |
|---|---|---|
all | All | Shows all events (pageviews, sessions, custom events). |
pageview | Views | Shows only pageview events. |
session | Visitors | Shows only new session start events. |
event | Events | Shows only custom events. |
Sources: src/app/(main)/websites/[websiteId]/realtime/RealtimeLog.tsx:28-60
The component dynamically renders details for each log entry based on its type (__type):
- Event: Displays the event name and the URL where it occurred.
- Pageview: Displays the URL of the viewed page.
- Session: Displays a summary of the visitor's country, browser, OS, and device.
Sources: src/app/(main)/websites/[websiteId]/realtime/RealtimeLog.tsx:81-125
Data Collection
The data displayed in the Real-time View originates from the client-side tracking script (tracker/index.js). This script automatically tracks page views and can be used to send custom events and identify users.
- Page Views: A page view is tracked automatically on initial page load and on history changes (e.g., in a Single Page Application).
- Custom Events: Custom events can be tracked using
window.umami.track('event-name', { ...data }). - Identify: User properties can be associated with a session using
window.umami.identify({ ...data }).
All tracked data is sent to the collection API endpoint, which then stores it in the database, making it available for the Real-time View.
Sources: src/tracker/index.js:156-177