How to use the Custom Request Processing Function

The Custom Request Processing Function is a special variable in Matomo Tag Manager (MTM) that lets you intercept and modify tracking data before it is sent to Matomo, such as renaming an event category or standardising site search keywords.

Instead of updating individual tags or changing your website’s source code, use the variable to handle these changes dynamically. It inspects and modifies the tracking request at runtime and allows for centralised logic that’s easy to maintain and update.

This guide explains how to configure the Custom Request Processing Function variable in Matomo Tag Manager. Before you start, ensure that Matomo Tag Manager is set up and actively tracking page views on your website.

Create a new Variable

1. Go to Matomo > Tag Manager and open your container.
2. Navigate to Variables and click Create New Variable.
3. Choose the Custom Request Processing Function and provide a custom name (optional).
4. In the JavaScript Function field, enter your custom function script using this format:
   function(request){
//custom logic
return request;
}
5. Click Create New Variable to save.
   

Example 1: Modify event category

If your tracking setup logs event categories that you want to change without editing the tags directly, you can rewrite those values with a processing function. This example converts the event category 'iframe' to 'Contact request' dynamically:

function(request){
  try {
    var urlParams = new URLSearchParams(request);

    if (urlParams.get('e_c') === 'iframe') {
      urlParams.set('e_c', 'Contact request');
      request = urlParams.toString();
    }

    return request;
  } catch (e) {
    return request;
  }
}

Example 2: Replace site search keywords

To standardise or modify internal site search keywords for your reports, you can use a script to apply these changes. This example uses the following JavaScript function to replace the search term 'employees' with 'HR Portal' before it is reported in Matomo:

function(request){
  if (typeof request === 'string') {
    const cleaned = request.trim().toLowerCase();

    if (cleaned === 'employees') {
      return 'HR Portal';
    }
    return request.trim();
  }
  return request;
}

Edit the Matomo Configuration Variable

By adding the Custom Request Processing Function variable to the Matomo Configuration variable, the function will run for every Matomo tracking tag that uses that Configuration variable.

1. Navigate to Variables and edit the Matomo Configuration Variable linked to your Matomo tracking tag.
2. Scroll down to the Custom Request Processing Function field and choose the newly-created variable. Note only one JavaScript function can be selected for the Matomo Configuration variable.
3. Click Update to save the changes.

Validate the configuration

Before publishing your Tag Manager container, it’s important to test and confirm the Custom Request Processing Function is working correctly.

1. Open your website and perform the relevant test action, e.g., use the site search and type in employees or trigger an event to see the event category modified for reports.
2. Use the Preview / Debug mode to view the Variables tab and check the right details were captured.
3. Open Visitors > Visits Log or the Real-time report to verify the data sent to Matomo.
4. For the Example 1: Modify event category, the event category is dynamically modified from iframe (as defined in the event tracking tag) to Contact Request.
   
5. For the Example 2: Replace site search keywords, the internal site search keyword is dynamically modified from employees to HR Portal.
   

What if the script doesn’t work?

The following points may help you to identify issues with the script and Tag Manager configuration.

• Test your script independently from Tag Manager to isolate syntax or logic errors.
• Ensure the function returns a value and uses the correct format.
• Check that your variable is correctly referenced in the Matomo Configuration Variable. Only tags using this configuration will trigger the function.

When configured correctly, this variable offers a flexible and scalable way to customise tracking requests while simplifying tag maintenance.