OpenWikidubinc/dub

Referrers Data

Purpose and Scope

Referrers data helps a workspace understand where link traffic originates before a visitor reaches a Dub short link or tracked destination. In the product documentation, this is described as both the referring domain and the full referring URL, which lets marketers separate broad channel performance from precise placement performance. In the repository, that idea appears in the analytics UI as a dedicated Referrers tab beside UTM Parameters, and in the OpenAPI analytics response family as separate schemas for domain-level and URL-level results. This page focuses on how that concept is represented across the dashboard, shared analytics types, and API surface.

Sources: apps/web/ui/analytics/referrers-utms.tsx, apps/web/lib/openapi/analytics/index.ts

A useful way to read this area is to treat referrer analytics as one grouped view over the same underlying analytics retrieval system. The UI does not define a standalone referrer service; instead, it asks the shared analytics filter hook for a particular grouping and then renders that grouped result in the analytics card. The API has the same shape: a single analytics retrieval operation accepts query parameters, and the response type varies based on the requested event and grouping. That keeps referrers consistent with other analytics dimensions such as devices, countries, browsers, and top links.

Sources: apps/web/ui/analytics/referrers-utms.tsx, apps/web/lib/analytics/types.ts, apps/web/lib/openapi/analytics/index.ts

Relevant Source Files

  • apps/web/ui/analytics/referrers-utms.tsx — Implements the dashboard card that lets users switch between Referrers and UTM Parameters, choose the domain or URL subtab, load grouped analytics data, and apply query-string filters.
  • apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/client.tsx — Wraps the dashboard analytics page with workspace loading and event-limit gating before analytics children render.
  • apps/web/lib/analytics/types.ts — Defines shared TypeScript types for analytics filters, group-by options, response options, events filters, views, and sale units.
  • apps/web/lib/analytics/utils/index.ts — Re-exports analytics utility modules used by surrounding analytics workflows, including CSV conversion, query-string editing, export formatting, interval data, and plan date-range validation.
  • apps/web/lib/openapi/analytics/index.ts — Declares the OpenAPI path for retrieving analytics and includes response variants for referrer domains and referrer URLs.
  • apps/web/ui/analytics/events/index.tsx — Shows how real-time events are presented in the analytics area and how plan-based upgrade messaging surrounds detailed event streams.

Dashboard Model

The dashboard implementation uses a combined component for Referrers and UTM Parameters because both features answer a similar question: which external campaign or traffic source should the user filter by? The component defines two top-level tabs. The Referrers tab has two subtabs: a domain view and a URL view. The UTM tab has subtabs derived from the plural UTM schema list. When the user changes between the top-level tabs, the component resets the selected subtab to a valid default, preventing a UTM grouping from accidentally being reused while the Referrers tab is selected.

Sources: apps/web/ui/analytics/referrers-utms.tsx

Filtering is handled through query parameters rather than private component state alone. The component computes the singular analytics endpoint name for the selected subtab, checks whether that parameter already exists in the current URL, and writes selected values back as a comma-separated filter. Clearing the filter removes that parameter and resets temporary selections. This is important for referrer analysis because a user can click into one or more source domains, apply them as filters, and keep the analytics page shareable or restorable through the browser URL. The same mechanism also allows the rest of the analytics provider to react to the active filter.

Sources: apps/web/ui/analytics/referrers-utms.tsx

System-to-Code Mapping

At the type layer, referrer data is not isolated from the rest of analytics. Shared analytics types derive their group-by options from the valid analytics endpoint list and derive response shapes from the analytics response schema object. The filter types also include workspace, date, link, partner, and availability fields used by many analytics screens. That shared model matters because referrer results can be requested for a single link, a domain, or a broader workspace context, depending on the query supplied to analytics retrieval. Referrers therefore participate in the same typed contract as time series, location, device, and conversion-oriented analytics.

Sources: apps/web/lib/analytics/types.ts

The OpenAPI mapping is the public contract for developers who fetch referrer data outside the dashboard. It exposes a single GET operation on the analytics path with the operation identifier for retrieving analytics. Its query parameters come from the analytics query schema, and its successful response is a union of possible analytics result shapes. Among those variants are arrays for referrer domains and referrer URLs, alongside other grouped analytics arrays. This confirms that referrer analytics is part of the generated API family rather than only a dashboard convenience.

Sources: apps/web/lib/openapi/analytics/index.ts

Execution Flow

A typical dashboard flow begins when the analytics page is allowed to render. The dashboard client first waits for workspace state, shows a layout loader while that state is unresolved, and can display a workspace event-limit screen when the workspace has exceeded allowed events. After that gate, the analytics UI can mount its provider and child components. Inside the Referrers and UTM card, the selected analytics tab from context determines whether the component should read ordinary counts or the selected sale unit. That distinction lets the same visual grouping compare click volume, lead counts, sales counts, or sales value depending on the active analytics event.

Sources: apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/client.tsx, apps/web/ui/analytics/referrers-utms.tsx

Once the component has a subtab, it requests two related data sets through the analytics filter option hook. One call respects the current grouping filter, and the other omits the group-by filter key. This lets the UI compare currently filtered results with the broader list used for selection and display. The component also resets selected items whenever the top-level tab or subtab changes, which avoids applying stale domain choices to full URL analytics or stale referrer choices to UTM analytics. That reset behavior is a small but important edge case in an interactive analytics screen.

Sources: apps/web/ui/analytics/referrers-utms.tsx

API Components

For API consumers, the central entry point is the analytics retrieval operation. The operation summary says it retrieves analytics for a link, a domain, or the authenticated workspace, and the description states that the response type depends on query parameters. In practice, a referrer-domain request should choose the analytics event to measure and the referrer grouping to aggregate by; a full-referrer-URL request uses the URL grouping. The official examples show the intent with clicks over a recent interval for a specific link, while the source confirms the response schemas that represent referrer domains and URLs.

Sources: apps/web/lib/openapi/analytics/index.ts

Compact reference for this page: the public OpenAPI path is GET analytics; the operation identifier is retrieveAnalytics; the Speakeasy override name is retrieve; the tag is Analytics; the security requirement is token authentication; the query schema is the shared analytics query schema; and the documented success response is a union that includes arrays for referers and referer_urls. The implementation spelling in code uses referers for the grouped endpoint and response key, while the reader-facing label in the UI is Referrers. Developers should follow the generated SDK or OpenAPI schema for exact parameter names in their environment.

Sources: apps/web/lib/openapi/analytics/index.ts, apps/web/ui/analytics/referrers-utms.tsx

Events, Plans, and Exports

Referrer analytics is related to, but different from, the real-time events stream. The events UI wraps its table in the analytics provider, keys the table by selected analytics tab, and shows a Business-plan upgrade overlay for detailed real-time streams when the workspace plan is free or pro. Referrer data is an aggregated grouping that answers where traffic came from; the events stream is a row-level operational view of individual clicks, QR scans, leads, sales, or related events. Readers should use grouped referrers for source analysis and events when they need detailed chronological inspection.

Sources: apps/web/ui/analytics/events/index.tsx

The analytics utility export barrel indicates supporting workflows around the main analytics experience. CSV conversion and export formatting support downloading analytics for offline analysis, query-string editing supports the same URL-driven filtering pattern seen in the referrers card, interval data supports time-bucketed reporting, and plan-based date-range validation helps keep analytics requests within product constraints. These utilities are not referrer-specific, but they explain why referrer analytics behaves consistently with other dashboard analytics dimensions and why exported or filtered reports can share common formatting and date handling.

Sources: apps/web/lib/analytics/utils/index.ts

Implementation Details and Edge Cases

Two implementation details are worth noting when changing or consuming this area. First, the dashboard presents polished labels while preserving internal endpoint names. The tab identifier and response schema use the repository’s established referer spelling, while visible UI text says Referrers and the subtab labels are Domain and URL. Second, the component clears temporary selections on tab changes and deletes query parameters when no values remain. These behaviors protect users from confusing mixed filters, especially when moving between referrer domains, full referrer URLs, and UTM campaign dimensions during the same analysis session.

Sources: apps/web/ui/analytics/referrers-utms.tsx

When investigating surprising referrer analytics, separate source attribution from geolocation or event availability concerns. Referrer data identifies traffic origins through domains and URLs, while location data can be affected by network routing or proxies, and detailed event streams may depend on plan level. The dashboard code reflects those boundaries by placing referrer grouping in the aggregate analytics card, enforcing workspace event limits before page rendering, and showing upgrade guidance around real-time events. The next step for a developer is usually to confirm the group-by parameter, active URL filters, selected event tab, and plan gating before looking deeper into ingestion or storage.

Sources: apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/client.tsx, apps/web/ui/analytics/events/index.tsx, apps/web/ui/analytics/referrers-utms.tsx

Read Analytics Overview for the broader retrieval pipeline and reporting model. Read Location Data, Device Data, and UTM Data to compare other supported analytics dimensions with referrer grouping. Read Analytics API for the complete retrieve operation, query parameters, and response families. Read Track Leads, Sales, and Opens when you need to understand the conversion events that can be counted or valued inside grouped analytics views.

Ask a question...