Shareable Dashboards
Relevant source files
The following files were used as context for generating this wiki page:
The Shareable Dashboards feature allows users to generate a unique, publicly accessible, read-only URL for a specific website's analytics dashboard. This enables sharing website statistics with external stakeholders without granting them access to the user's Umami account. The feature is managed within a website's settings, where a share URL can be enabled, disabled, or regenerated.
The system works by associating a randomly generated shareId with a website. When a user visits the /share/{shareId} URL, the application fetches the corresponding website data and presents a restricted, non-interactive version of the main analytics dashboard.
Architecture Overview
The feature involves three main parts: the settings UI for managing the share URL, a public page to display the shared dashboard, and a backend process to link a shareId to a websiteId.
This diagram illustrates the high-level flow of creating and viewing a shared dashboard.
Creating and Managing a Share URL
Website owners can manage a dashboard's shareability from the website's settings page. The WebsiteShareForm component provides the user interface for this functionality.
Sources: src/app/(main)/websites/[websiteId]/settings/WebsiteShareForm.tsx
UI Components and Logic
The form consists of a switch to enable/disable sharing, a read-only text field to display the generated URL, and buttons to regenerate the ID or save changes.
| Component | Description | Source |
|---|---|---|
Switch | Toggles the currentId state between null and a newly generated ID. Labeled "Enable share URL". | WebsiteShareForm.tsx:55-57, messages.ts:60 |
TextField | Displays the full, read-only shareable URL. Includes a copy button. | WebsiteShareForm.tsx:61-62 |
Button (Regenerate) | Calls handleGenerate to create a new random shareId. | WebsiteShareForm.tsx:64-66 |
FormSubmitButton (Save) | Submits the form, persisting the shareId to the website record. | WebsiteShareForm.tsx:71 |
The shareId is a 16-character random string generated by getRandomChars(16). The final URL is constructed based on the environment, either using a cloudUrl or the current window's origin.
Sources: src/app/(main)/websites/[websiteId]/settings/WebsiteShareForm.tsx:13, 29-35
Data Flow: Saving the Share ID
When a user enables sharing and clicks "Save", the WebsiteShareForm component initiates an API call to associate the generated shareId with the website.
This sequence diagram shows the process of creating and saving a new share URL.
Viewing a Shared Dashboard
A shared dashboard is rendered by the SharePage component, which is a client-side component responsible for fetching data and displaying the analytics view.
Sources: src/app/share/[...shareId]/SharePage.tsx
Page Rendering and Data Fetching
The page extracts the shareId from the URL and uses the useShareTokenQuery hook to fetch a shareToken. This token contains the websiteId needed to load the dashboard components.
The core rendering logic is as follows:
- The
SharePagecomponent receives theshareId. - The
useShareTokenQuery(shareId)hook is called to fetch the share token. - While loading, the component returns
null. - Once the
shareTokenis loaded, it provides thewebsiteIdto aWebsiteProvider. - Standard components like
WebsiteHeaderandWebsitePageare rendered, but with modifications for the public view (e.g.,showActions={false}).
Sources: src/app/share/[...shareId]/SharePage.tsx:15, 25-30
This sequence diagram shows the data flow when a user accesses a share URL.
Content and Restrictions
The shared dashboard is a read-only version of the standard dashboard.
- The
WebsiteHeaderis rendered withshowActions={false}, which hides controls like the date range picker and settings button. - The
WebsitePanelscomponent detects if it is on a share page by checking if the URL path includes/share/. - When
isSharePageis true, an additional row with an Events table and chart is displayed, which is not part of the default dashboard view.
Sources: src/app/share/[...shareId]/SharePage.tsx:28, src/app/(main)/websites/[websiteId]/WebsitePanels.tsx:16, 75-89
Configuration and Constants
The behavior of the shareable dashboards feature is governed by several constants defined in the application.
| Constant | Value | Description | File |
|---|---|---|---|
SHARE_ID_REGEX | ^[a-zA-Z0-9]{8,50}$ | A regular expression used to validate the format of a shareId. | lib/constants.ts:241 |
SHARE_TOKEN_HEADER | x-umami-share-token | The HTTP header name used to pass the share token for authentication. | lib/constants.ts:10 |
labels.enableShareUrl | "Enable share URL" | The text label for the switch that controls the feature. | components/messages.ts:60 |
messages.shareUrl | "Your website stats are publicly available at the following URL:" | The descriptive text shown above the share URL. | components/messages.ts:399 |
The shareId is generated using getRandomChars(16) in WebsiteShareForm.tsx and getRandomChars(9) in LinkEditForm.tsx for links, indicating a flexible length that must conform to the SHARE_ID_REGEX.
Sources: src/app/(main)/websites/[websiteId]/settings/WebsiteShareForm.tsx:13, src/app/(main)/links/LinkEditForm.tsx:18, src/lib/constants.ts:241