How do I customise the Matomo Campaign parameters pk_campaign and pk_kwd?

On-Premise

Matomo detects campaign names and keywords through a set of default parameters for campaign tracking. The recommended defaults use the mtm_ prefix, while pk_ parameters remain supported for backwards compatibility. Matomo can also process Google Analytics campaign parameters such as utm_.

Default parameter names that Matomo will read:

  • campaign name parameters: mtm_campaign, matomo_campaign, pk_campaign, piwik_campaign, utm_campaign, utm_source, utm_medium
  • campaign keyword parameters: mtm_kwd, mtm_keyword, pk_kwd, piwik_kwd, pk_keyword, utm_term

Override default campaign parameters

To use custom campaign parameter names reliably, define the new parameter in the [MarketingCampaignsReporting] and [Tracker] sections of config.ini.php.

Matomo reads campaign parameters in both sections to ensure consistent behaviour across campaign detection, reporting, and keyword processing and prevents the default parameters (mtm_*, pk_*, and utm_*) from being used. Note: If the custom names appear only under [MarketingCampaignsReporting], Matomo continues to process default parameters.

Update the server configuration

The following example demonstrates how to replace the default parameter names with campaign and keyword.

  • Edit config/config.ini.php and add the custom names to both sections. Both settings accept comma-separated lists. Matomo uses the first non-empty value it finds:
[MarketingCampaignsReporting]
campaign_name_parameter = "campaign"
campaign_keyword_parameter = "keyword"

[Tracker]
campaign_var_name = "campaign"
campaign_keyword_var_name = "keyword"

Update the JavaScript tracker

  • Edit the Matomo tracking code and add the custom parameter names before the trackPageView call:
_paq.push(['setCampaignNameKey', 'campaign']);
_paq.push(['setCampaignKeywordKey', 'keyword']);

Additional notes:

  • These two functions also accept an array of strings. If an array of names is specified, the first non empty campaign or keyword parameter value will be selected.
  • The Campaign parameters can be used in the query string or in the hash as well (for cleaner canonical URLs), such as: landing.html#pk_campaign=my campaign
  • To measure more than campaign name and keyword and up to five campaign dimensions, as well as support other standard UTM campaign tags, use the free plugin [MarketingCampaignsReporting]
  • To find out the true value and success of all of your marketing campaigns, we recommend using the Multi Channel Conversion Attribution premium feature.

You may also be interested in creating an affiliate system with Matomo to track new customers and revenue from affiliates.

Previous FAQ: URL Builder – Marketing Campaign Tracking