Reports: UTM & Attribution

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/(main)/websites/[websiteId]/(reports)/utm/UTM.tsx
• src/app/(main)/websites/[websiteId]/(reports)/attribution/Attribution.tsx
• src/queries/sql/reports/getUTM.ts
• src/queries/sql/reports/getAttribution.ts
• prisma/schema.prisma
• src/components/messages.ts
• src/lang/en-US.json

The UTM and Attribution reports are powerful analytics features within Umami designed to provide insights into marketing campaign performance and conversion drivers. The UTM report allows users to track and analyze traffic based on Urchin Tracking Module (UTM) parameters, offering a clear view of campaign effectiveness.
Sources: src/lang/en-US.json:204, src/components/messages.ts:335-338

The Attribution report goes a step further, helping to identify which marketing channels and touchpoints contribute to user conversions, such as page views, custom events, or revenue. It allows users to see how visitors engage with marketing efforts and what ultimately drives them to a goal.
Sources: src/lang/en-US.json:22, src/components/messages.ts:241-244

Data Model

The core of UTM and attribution tracking is the WebsiteEvent table, which records every event, including page views and custom events. This table stores UTM parameters, referrer information, and various ad click identifiers.

Sources: prisma/schema.prisma:105-150

Entity Relationship Diagram

The following diagram illustrates how WebsiteEvent relates to other key tables in the database.

Key WebsiteEvent Fields

These fields in the WebsiteEvent model are essential for UTM and attribution analysis.

Field	Type	Description
utmSource	String?	The source of the traffic (e.g., google, newsletter).
utmMedium	String?	The marketing medium (e.g., cpc, email).
utmCampaign	String?	The specific campaign name.
utmContent	String?	Used to differentiate ads or links that point to the same URL.
utmTerm	String?	The paid keywords.
referrerDomain	String?	The domain of the referring URL.
gclid	String?	Google Click Identifier.
fbclid	String?	Facebook Click Identifier.
msclkid	string?	Microsoft Click Identifier.
ttclid	string?	TikTok Click Identifier.
lifatid	string?	LinkedIn First-Party Ad Tracking ID.
`twclid``	string?	Twitter Click Identifier.

Sources: prisma/schema.prisma:114-126

UTM Report

The UTM report provides a breakdown of website views for each of the five standard UTM parameters: source, medium, campaign, content, and term.

Sources: src/app/(main)/websites/[websiteId]/(reports)/utm/UTM.tsx:28-30, src/components/messages.ts:335-338

Frontend Component: UTM.tsx

The UTM component is responsible for rendering the UTM report page.

• It uses the useResultQuery hook to fetch data for the 'utm' report type.
• It iterates over a UTM_PARAMS constant array (['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term']).
• For each UTM parameter, it displays a Panel containing:
  • A ListTable showing the UTM values and their corresponding view counts.
  • A PieChart visualizing the distribution of views across the different UTM values.

Sources: src/app/(main)/websites/[websiteId]/(reports)/utm/UTM.tsx:18-62

Data Flow

The diagram below shows the sequence of events when a user views the UTM report.

Backend Logic: getUTM.ts

The getUTM function retrieves the data from the database. It supports both PostgreSQL and ClickHouse.

• The function takes websiteId, startDate, and endDate as arguments.
• It constructs a query that selects a specific UTM column (e.g., utm_source) and counts the number of page views (count(*)).
• It groups the results by the UTM parameter value.
• The results for all five UTM parameters are collected and returned as a single object.

Sources: src/queries/sql/reports/getUTM.ts:11-61

Attribution Report

The Attribution report helps users understand which channels and campaigns lead to conversions. It supports different attribution models and can track conversions based on page paths, events, or revenue.

Sources: src/app/(main)/websites/[websiteId]/(reports)/attribution/Attribution.tsx:21-30, src/queries/sql/reports/getAttribution.ts:13-20

Frontend Component: Attribution.tsx

The Attribution component renders the report.

• It uses the useResultQuery hook to fetch data for the 'attribution' report type, passing parameters like model, type, and step.
• It displays key metrics like total visitors, visits, and views in a MetricsBar.
• It uses a reusable AttributionTable component to display breakdowns for:
  • Referrers
  • Paid Ads
  • UTM Source, Medium, Campaign, Content, and Term.
• The metric displayed is either "Visitors" or "Revenue", depending on whether a currency is specified.

Sources: src/app/(main)/websites/[websiteId]/(reports)/attribution/Attribution.tsx:32-106

Data Flow

Backend Logic: getAttribution.ts

The getAttribution function is responsible for the complex logic of calculating attribution. It has distinct implementations for relational databases (PostgreSQL) and ClickHouse.

Parameters

The function's behavior is controlled by these parameters:

Parameter	Type	Description
websiteId	string	The ID of the website to query.
startDate	Date	The start of the date range.
endDate	Date	The end of the date range.
model	string	The attribution model, e.g., 'first-click' or 'last-click'.
type	string	The conversion type, e.g., 'path' for page view or 'customEvent'.
step	string	The specific URL path or event name that constitutes a conversion.
currency	string?	Optional currency code for revenue attribution.

Sources: src/queries/sql/reports/getAttribution.ts:13-20

Query Logic

The query logic can be summarized in the following steps:

1. Identify Conversion Events: A WITH clause (events or revenue_events) selects all sessions that had the specified conversion goal (step) within the date range.
2. Apply Attribution Model: A second WITH clause (model) identifies the specific touchpoint event in each conversion session based on the selected model.
   • first-click: Selects the earliest website_event for the session.
   • last-click: Selects the latest website_event that occurred before the conversion event.
3. Calculate Attribution: A series of SELECT statements join the model results back to website_event to get the attribution data (referrer, UTM, ad click ID) for that touchpoint.
4. Aggregate Results: The queries group by the attribution dimension (e.g., referrer_domain, utm_source) and aggregate the results, either by counting distinct sessions or summing revenue.
5. Paid Ads Detection: A special query checks for the presence of various ad click identifiers (gclid, fbclid, etc.) to attribute conversions to paid ad channels.

This logic is executed separately for referrers, paid ads, and each of the five UTM parameters.

Sources: src/queries/sql/reports/getAttribution.ts:40-230

This is a simplified flowchart of the query logic for a single attribution source (e.g., Referrers).