ChannelGrouping · Documentation

Group hundreds of traffic sources into the marketing channels you actually steer: Organic, Paid, Email, Social or your own.

Overview

Group your traffic sources into meaningful marketing channels and understand your marketing performance at a glance.

The problem

Matomo shows you hundreds of referrers, campaigns and traffic sources. But how much traffic really comes from email marketing? And how do your paid campaigns compare to organic search?

The solution

Channel Grouping combines your traffic sources into channels, exactly the way you need them.

Features

Flexible rule-based mapping

Define precise rules that decide which visit belongs to which channel.

11 operators: equals, does not equal, contains, does not contain, starts with, ends with, matches regex, is empty, is not empty, is in list, is not in list
Bundled source lists: search engines, social networks, video platforms, shopping sites, email and AI assistants, including sources from Germany, Austria and Switzerland
Source and medium: derived from campaign, click ID and referrer, plus rules on the landing page (URL or path)
Any combination: rules are combined with OR, conditions within a rule with AND
Channel conditions: apply to all rules of a channel
Order: channels are checked from top to bottom, and the first match wins. You change the order with a click
Value suggestions: values from your visits of the last 30 days, including campaigns and custom dimensions

Ad clicks even without UTM parameters

The plugin recognises visits from ads by the click ID in the landing page URL, even when no UTM parameters are set.

Click IDs from Google Ads, Microsoft Advertising, Meta, TikTok, LinkedIn, X, Snapchat, Pinterest and Yandex, plus Mailchimp
Assigned correctly: a Google Ads click lands in Paid Search instead of Organic Search
Data-minimal: only the type of click ID is stored (such as "gclid"), never its value
Usable everywhere: as a dimension in rules, as the segment Click ID type and in the Visits Log

Editor with draft, test visit and impact

You edit a grouping completely in one editor and save it with one click.

Draft and active: prepare changes as a draft; only active groupings count for tracking and reports
Test visit: enter a landing page or referrer URL and see which channel applies and why
Impact before saving: visits per channel before and after, calculated on the newest visits of the last 30 days, with examples
Apply your way: a change applies only to new visits, to the standard period or from a day of your choice
Duplicate: copy a grouping as a draft and rework it calmly
Version history: every change is kept as a version. Compare versions, load them into the editor or copy them as a new grouping
Dark mode: the admin page follows Matomo's dark mode

Conversions and revenue per channel

See not just visits, but conversions and revenue per channel.

Conversions, conversion rate and revenue right in the channel report
Revenue from goals and ecommerce
The report also appears on Matomo's goal pages under Goals by Referrers
Ecommerce per channel under Ecommerce → Sales: orders, revenue, conversion rate, average order value and products purchased, with abandoned carts separately

Goal attribution

Which channel really brought the purchase? Two additional reports under Goals and Ecommerce → Sales answer that.

Channel (last non-direct touch): conversions from direct visits count for the channel the visitor last came through
Channel (first touch): every conversion counts for the channel of the first visit
90-day lookback, adjustable or switchable off in the Matomo configuration
Also in email reports and through the API

Multiple websites

One grouping for all your websites, or individual settings per website.

Applies to	Meaning
Only this website	applies to this website only
Selected websites	applies to the websites you select
All websites	applies to all websites; only super users can create it

One grouping is active per level. If several levels apply to a website, the more specific one takes priority.

Evolution over time

Follow how your channels develop.

The graph Channel Grouping Over Time above the report, both in full width
Several metrics to choose from (visits, actions, conversions, revenue)
Show or hide channels via the legend

Segmentation

Use your channels as a segment in every Matomo report.

Dimension Channel Group in the segment editor, with suggestions from your channels
The report, goals, segment and Visits Log show the same channel for every visit
Combinable with all other segments

Sources per channel

Click a channel to see the individual referrers and campaigns behind it.

Sortable by every metric
Export like any Matomo report, for example as CSV, JSON or XML

Automatic re-assignment

When you change rules or channels, they apply to new visits at once. The plugin re-assigns past visits in the background and has the affected reports recalculated, as far back as Matomo re-archives reports (6 months by default). The admin page shows the progress.

For older periods or targeted runs, there is a command for the command line:

# Test first, without changing anything
./console feinwerkchannelgrouping:backfill --dry-run

# Re-evaluate all visits of one website in a period
./console feinwerkchannelgrouping:backfill --idsite=1 --from=2025-01-01 --to=2025-12-31 --force

The command has the reports of that period recalculated by itself.

Export and import

Back up your configuration or move it to another Matomo instance.

Export a grouping as a JSON file
Import with validation of the file, always as a draft, also for exports from older versions
Handy for moving a grouping from a test instance to production

Custom dimensions

Use your custom dimensions in channel rules.

Visit dimensions: detected automatically and available in rules
Flexible rules: combine them with referrer and campaign data
Your own classification: group by customer type, region or any other value

Note: only visit dimensions are supported. Action dimensions (for example for individual pageviews) are not available, because the channel is assigned per visit.

Examples:

Channels by customer type, such as "B2B" and "B2C"
Internal campaign classification
Channels by region or product

Metrics at a glance

Metric	Meaning
Visits	number of visits per channel
Actions	pageviews, downloads, events and other actions
Actions per Visit	average number of actions per visit
Avg. Time on Website	average duration of a visit
Bounce Rate	share of visits with only one action
Conversions	number of goals reached
Conversion Rate	share of visits with a conversion
Revenue	revenue from goals and ecommerce

Preconfigured channels

Start right away with the default grouping ("Default Channel Grouping v2"), modelled on the default channel groups of Google Analytics 4. Its 19 channels are checked in this order:

Channel	Captures
Direct	visits without source and medium, for example from bookmarks or a typed address
Cross-network	campaigns whose name contains "cross-network"
Paid Shopping	paid visits from shopping sites or shopping campaigns
Paid Search	paid visits from search engines, such as Google Ads clicks
Paid Social	paid visits from social networks
Paid Video	paid visits from video platforms
Display	banner ads with a medium such as `display`, `banner` or `cpm`
Paid Other	other paid visits (medium such as `cpc`, `ppc`, `paid…`, `retargeting`)
Organic Shopping	unpaid visits from shopping sites
Organic Video	unpaid visits from video platforms
Organic Social	unpaid visits from social networks
Organic Search	unpaid visits from search engines
AI Assistants	visits from AI assistants such as ChatGPT, Perplexity or Gemini
Email	email campaigns and webmail, also with `utm_medium=newsletter`
Affiliates	campaigns with `utm_medium=affiliate`
Referral	referrals from other websites
Audio	campaigns with `utm_medium=audio`
SMS	campaigns via SMS
Mobile Push Notifications	campaigns via push notifications

Paid means the medium is, for example, cpc, ppc or paid_social, or a click ID such as gclid supplies it. As in Google Analytics 4, Direct only applies to visits without a medium. Everything else without a matching rule appears as Not assigned in the report. Adjust the channels or create your own. Existing groupings keep working unchanged.

Quick start

Install the plugin and activate the free MarketingCampaignsReporting plugin (recommended)
Open Administration → Websites → Channel Grouping
Click Create Default Grouping. The grouping is active right away; if the website already has one, it is created as a draft for you to check
Done: the report appears under Acquisition → Channel Grouping

From now on, new visits get their channel at tracking time. The plugin assigns past visits in the background, and the admin page shows the progress.

Technical details

Requirements

Matomo 5.3 or later
PHP 8.1 or later
Recommended: the free MarketingCampaignsReporting plugin for campaign fields (utm_source, utm_medium and more). Without it, the default grouping recognises campaign links only by click IDs

Archiving and data

The channel is determined at tracking time and stored with each visit. The report, goals, segment and Visits Log use this channel. Your referrer and campaign data stay unchanged.
Of click IDs, only the type is stored (one additional column in the visits table), never the value.
Every saved change of a grouping is kept as a version (the newest 50 per grouping), shown in the editor's History tab.
For attribution the plugin recognises visitors, like Matomo, by their visitor ID. Without cookies or a user ID an earlier visit may be missing.
The report is as current as Matomo's last archiving run.
Everyone with at least write access to the website can edit groupings; groupings for all websites need a super user.

Available dimensions

Referrer:

referrer_type (direct, search, social, website, campaign, ai)
referrer_name (for example "Google", "Facebook")
referrer_url
referrer_keyword

Campaign (UTM, with MarketingCampaignsReporting):

campaign_name (utm_campaign)
campaign_source (utm_source)
campaign_medium (utm_medium)
campaign_content (utm_content)
campaign_keyword (utm_term)
campaign_id (utm_id)

Source, medium, landing page, click ID:

source and medium (derived from campaign, click ID and referrer)
landing_page_url and landing_page_path
click_id (click ID type, such as gclid)

Custom dimensions:

dimension1, dimension2 and more (visit dimensions)

Operators

Operator	Meaning
equals	exact match
does not equal	no match
contains	contains the value
does not contain	does not contain the value
starts with	starts with the value
ends with	ends with the value
matches regex	regular expression without delimiters, at most 500 characters
is empty	field is empty
is not empty	field has a value
is in list	value is in one of the bundled source lists
is not in list	value is not in the chosen source list

Upper and lower case are ignored unless the field Aa (Case Sensitive) is ticked.

API

The channel report is available through Matomo's Reporting API as FeinwerkChannelGrouping.getChannels, for example for exports or dashboards. Through the API, FeinwerkChannelGrouping.saveGrouping saves a grouping as a whole, getChannelsLastNonDirect and getChannelsFirstTouch return the attribution reports, getGroupingVersions the version history, getSourceLists returns the source lists and getAvailableOperators the value type per operator.

Upgrading from ChannelGrouping

Up to version 0.5 this plugin was called ChannelGrouping. Install and activate FeinwerkChannelGrouping: it takes over groupings, channels, rules, the channel assignment of visits, archived reports, settings, email reports and saved views, and removes the old plugin automatically. Do not uninstall the old plugin yourself, as that would delete the channel data.

Use cases

Marketing truth at a glance: How much traffic really comes from email? How does paid compare to organic? One report answers it.
Rules, your way: 11 operators for precise, rule-based mapping. Your channel definitions, not someone else's.
Your tracking stays as it is: Referrer and campaign data stay exactly as tracked. The plugin adds the channel to each visit. You can refine rules anytime and re-assign past visits.

Step-by-step setup

How to install the plugin is described in Installing plugins. It needs Matomo 5.3 or later. Then:

Activate MarketingCampaignsReporting (recommended). With the free MarketingCampaignsReporting plugin, the campaign fields Campaign source, Campaign medium and more (utm_source, utm_medium and so on) are available in rules, and the default grouping recognises all campaigns. Without it, the default grouping recognises campaign links only by click IDs; other campaigns appear as Not assigned.
Open the admin page. Select the website and open Administration → Websites → Channel Grouping (page Manage Groupings).
Create your first grouping. The quickest way is Create Default Grouping. You get the "Default Channel Grouping v2", modelled on the default channel groups of Google Analytics 4: 19 channels from Direct through paid and organic search, social, video and shopping to Email, Affiliates, Referral, Audio, SMS, Mobile Push Notifications and AI Assistants. It uses bundled source lists including sources from Germany, Austria and Switzerland. If a grouping is already active for the website, the new one is created as a draft so you can check the impact before activating it. Alternatively, New grouping creates your own: a name, an optional Description, what it Applies to (Only this website, Selected websites or All websites (super users only)) and the Status. A Draft does not affect tracking or reports; only an Active grouping counts.
Edit in the editor. Edit opens a grouping with all channels, conditions and rules on one page. Add channel creates a channel with a Channel name and an optional Color, Duplicate channel copies an existing one as a template. Change the order with Move up and Move down: channels are checked from top to bottom, and the first matching channel wins. Under Applies to all rules of this channel you set conditions every visit of the channel must meet. Add rule (OR) and Add condition build the rules from a dimension, an operator and a value.
- Dimensions: referrer type, name, URL and keyword, the campaign fields, Source and Medium (derived from campaign, click ID and referrer), Landing page URL and Landing page path, Click ID type and your custom dimensions (visit scope).
- Operators: equals, contains, starts with, ends with, matches regex, is empty, each with its negation, plus is in list and is not in list. For the lists you pick one of the bundled source lists (search engines, social networks, video platforms, shopping sites, email, AI assistants); View list shows its entries.
- Values: the plugin suggests values from the visits of the last 30 days, for the landing page the most frequent entry pages.
Test before you save. In the Test visit tab you enter a landing page URL (also without "https://"), a referrer URL or single values and see which channel applies and which rule matches. The value table also shows the source, medium and click ID the plugin derives from them. In the Impact tab, Compute impact compares the newest visits of the last 30 days (at most 5,000): visits per channel before and after, plus examples of visits that get a different channel.
Save and apply. Save stores the whole grouping at once. For an active grouping you choose how the change is applied: Only new visits, the Standard period or From a day. The standard period reaches as far back as Matomo recalculates reports (setting rearchive_reports_in_past_last_n_months, default 6 months). The plugin then re-assigns past visits in the background and has the affected reports recalculated. While it runs, the admin page shows Updating channel assignment with the progress. The work is done by Matomo's scheduled task, which runs hourly together with archiving. When you activate a grouping, other active groupings of the same level become drafts after you confirm. The plugin keeps every saved change as a version (the newest 50 per grouping). The editor's History tab lists each version with time, user and change. Compare it with the previous version or with the editor (including unsaved changes) to see added, removed, renamed and moved channels, changed colours, conditions and rules. Load into editor brings back an older version (scope and status stay, and only Save applies it); Copy as new grouping (draft) copies it.

For older periods or targeted runs, use the command in your Matomo directory:
```
./console feinwerkchannelgrouping:backfill --dry-run                        # count only, change nothing
./console feinwerkchannelgrouping:backfill --idsite=1                       # assign visits without a channel
./console feinwerkchannelgrouping:backfill --idsite=1 --force               # re-evaluate all visits in the period
./console feinwerkchannelgrouping:backfill --from=2025-01-01 --to=2025-12-31 --force
```
Without --idsite, the command processes every website that has a grouping; without --from, it reaches as far back as the automatic re-assignment. Afterwards it marks the reports of that period for recalculation, and the next archiving run (./console core:archive) does the rest. --no-invalidate skips that step, --batch-size sets the amount per pass (100 to 10,000, default 2,000).
Open the reports. The report is under Acquisition → Channel Grouping: the graph over time at the top, below it the table with visits, actions, bounce rate, conversions and revenue per channel, both in full width. Click a channel to see its individual sources. For websites with ecommerce, Ecommerce → Sales → Channel Grouping shows orders, revenue, conversion rate, average order value and products purchased per channel, with abandoned carts separately. Under Goals and Ecommerce → Sales you also find the attribution reports (see below). In the segment editor the dimension is called Channel Group, so you can filter any other report by a channel.

Click IDs

Visits from ads on Google, Microsoft, Meta, TikTok, LinkedIn, X, Snapchat, Pinterest and Yandex, and from Mailchimp links, are recognised by the click ID in the landing page URL (such as gclid, msclkid, fbclid), even without UTM parameters. In the default grouping, a Google Ads click therefore lands in Paid Search instead of Organic Search. Only the type of click ID is stored (for example "gclid"), never its value. It is available as the dimension Click ID type in rules, as a segment and in the Visits Log.

Click IDs are recorded from the update to 0.9.0 on; older visits have none. Paid Search can therefore jump from the day of the update. Existing groupings use click IDs only if you add rules on Click ID type, Source or Medium.

Goal attribution

The Channel Grouping report credits a conversion to the channel of the visit in which it happens. Many purchases, though, come from a direct visit after the visitor first arrived through an ad or a search engine. For this, Goals and Ecommerce → Sales offer two more reports:

Channel (last non-direct touch): a conversion from a direct visit counts for the channel the visitor last came through, such as search engine, website, social network, AI assistant, campaign or ad (also recognised by click ID).
Channel (first touch): every conversion counts for the channel of the first visit within the lookback period.

The lookback is 90 days. The total of conversions stays the same; only their split across channels changes. Both reports are also available in email reports and through the API.

The plugin recognises visitors, like Matomo, by their visitor ID. Without cookies or a user ID an earlier visit may be missing, and so may visits on other devices. Visits whose raw data has already been deleted do not count. If there are no attributed conversions yet for a period or segment, the reports stay empty and say why.

You set the lookback and the models in the Matomo configuration (config/config.ini.php):

[FeinwerkChannelGrouping]
attribution_lookback_days = 90              ; 1 to 365 days
attribution_models = "last_non_direct,first_touch"   ; empty = attribution off

Practical examples

Newsletter separate from other email. Add a channel "Newsletter", move it above Email with Move up and give it the rule Campaign source equals newsletter. Since the first matching channel wins, newsletter clicks land there and all other emails stay in Email.

A naming convention for campaigns. Agree as a team which utm_medium values you use, for example cpc for search ads, paid_social for paid social ads, email, affiliate and display. Then one rule on Medium per channel is enough. For banner ads, add for example a channel "Display" with Medium matches regex ^(display|banner)$.

Separate paid and organic visits. The default grouping recognises paid visits by their medium (such as cpc, ppc, paid_social, retargeting), also when it is derived from a click ID such as gclid or msclkid, and assigns them via the source lists to Paid Search, Paid Social, Paid Video or Paid Shopping. Unpaid visits from the same sources land in the organic channels. For paid social ads we recommend utm_medium=paid_social with the network as utm_source.

Channels by landing page. Don't want job applicants mixed into your marketing report? Add a channel "Careers" at the top with Landing page path starts with /jobs. In the same way you can single out visits to a campaign page or a magazine section.

Your own shopping sources. A channel "Price comparison" with Source is in list Shopping sites combines idealo, Geizhals and other shopping sites. If a source is missing from the list, add a second rule for it with Source equals.

One rule set for several websites. Maintain one grouping for All websites (super users only) centrally. If a website needs its own channels, give it an additional active grouping for Only this website; the more specific one takes priority. Export and Import (a JSON file up to 2 MB) move a grouping to another Matomo instance. An import always arrives as a draft, and exports from older versions can be imported too.

Prepare changes calmly. Duplicate as draft creates a copy of the active grouping that you can change without moving tracking or reports. Check the result with Test visit and Impact. When everything fits, set the draft to Active; the previous grouping becomes a draft after you confirm.

Channels by your own attributes. Visit dimensions from Matomo's custom dimensions, such as a customer type, are available in rules. This lets you build, for example, a channel "B2B Organic".

Good to know

Evaluation order: channels are checked in the editor's order, from top to bottom, and the first matching channel wins. Within a channel, all conditions under Applies to all rules of this channel and at least one rule must match; within a rule, all conditions. A channel without rules applies to every visit that meets its conditions. Rules without conditions are removed when saving. Visits that match no channel appear as Not assigned. In the default grouping, Direct applies, as in Google Analytics 4, only to visits without a medium.
Draft and active: at most one grouping is active per level (this website, selected websites, all websites). If several levels apply to a website, the more specific one wins (this website before selected websites before all websites). Drafts do not affect tracking or reports.
Values and regex: comparisons ignore upper and lower case unless you tick the field Aa (Case Sensitive). Write regex patterns without delimiters, for example ^(cpc|ppc)$ (a / inside is fine), with at most 500 characters. Invalid patterns are rejected when you save, and patterns that abort during evaluation count as not matching.
Source lists: the lists come with the plugin and are maintained with new versions. You cannot edit them; add missing sources with a rule of your own.
One channel per visit, the same everywhere: the channel is determined at tracking time and stored with the visit. The report, goals, ecommerce, segment and Visits Log therefore show the same channel. If a visit starts directly and continues through a search engine or campaign within the same visit, it gets that source's channel. Landing page rules also apply retroactively. The report is as current as the last archiving run.
Conversions count reached goals, not converted visits. Sources without a name appear translated, for example as Direct entry.
Renaming channels: saved segments filter by channel name. After renaming a channel, adjust them. This also applies when you switch to the new default grouping, whose names partly differ (for example "Affiliates" instead of "Affiliate").
Updating to 0.10.0: coming from 0.9.x, the database structure does not change. So that the attribution reports also have values for the past, the update recalculates the channel reports of websites with goals or ecommerce once for the standard period (without segments). This adds archiving load once; no visits are re-assigned.
Updating to 0.9.0: the update needs Matomo 5.3 and adds one column to the visits table. On current MySQL and MariaDB versions this takes seconds, on MySQL 5.7 with very large tables longer: back up first and run it outside peak hours with ./console core:update. Existing groupings keep working unchanged, and no visits are re-assigned. For websites with ecommerce, the channel reports of the standard period are recalculated once. The backup of the old rule tables from 0.8.0 is deleted. If no click IDs are recorded afterwards, deactivate and activate the plugin once; this repeats the step without data loss.
Updating to 0.8.0: existing groupings moved into the new admin page and stayed active; rules without conditions were dropped. The order in the editor replaces the priority number. Change saved segments with & in a channel name to &.
Permissions: everyone with at least write access to the website can edit groupings; groupings for all websites need a super user. Groupings you may not change can still be viewed. The menu item Administration → Websites → Channel Grouping is visible with write access already. The report and the segment are available to everyone with view access.
API: besides getChannels, getChannelsLastNonDirect and getChannelsFirstTouch return the attribution reports, getGroupingVersions and getGroupingVersion the history. getSourceLists returns the source lists and getAvailableOperators names the value type (valueType) of each operator. saveGrouping saves a grouping as a whole, createDefaultGrouping creates the default grouping.
Troubleshooting: if the report stays empty, check that a grouping is active (not just a draft) and that archiving has run. For wrong assignments, use the Test visit. More in Troubleshooting.

Technical reference

Property	Value
Technical name	`FeinwerkChannelGrouping`
Current version	0.10.1
Matomo	≥ 5.3.0, < 6.0.0
PHP	≥ 8.1.0
License	paid
Database changes	No database schema change when updating from 0.9.x; updating from an older version adds one column to the visits table (log_visit), which on MySQL 5.7 with very large visit tables can take a while. The channel reports of sites with goals or ecommerce are recalculated once for the standard period (extra archiving load).

FAQ

Do I have to define everything myself?

No. A default grouping modelled on Google Analytics 4, with 19 channels such as Paid Search, Paid Social, Organic Search, Email and AI Assistants, is created with one click. You refine it or replace it with your own rules.

Which other plugins do I need?

We recommend the free MarketingCampaignsReporting plugin for campaign fields such as utm_source and utm_medium. Without it, the default grouping recognises campaign links only by click IDs. The plugin requires Matomo 5.3 or later.

What happens to unmatched traffic?

Visits that match no channel appear as "Not assigned" in the report, so your totals always add up and nothing silently disappears.

Does it modify my tracked data?

Your referrer and campaign data stay exactly as tracked. In addition, the plugin stores each visit's channel, determined at tracking time and used for segments, conversions and revenue. After rule changes, the plugin re-assigns past visits automatically.

Are Google Ads clicks recognised without UTM parameters?

Yes. The plugin recognises click IDs from Google Ads, Microsoft Advertising, Meta, TikTok, LinkedIn, X, Snapchat, Pinterest, Yandex and Mailchimp in the landing page URL. A Google Ads click therefore lands in Paid Search. Only the type of click ID is stored, never its value.

Which channel gets a purchase made on a direct visit?

In the Channel Grouping report, the channel of the purchase visit counts, so Direct. The attribution reports credit the purchase to the channel of the last non-direct visit or of the first visit within the 90 days before.