Manually report errors with Matomo Tag Manager

JavaScript applications can report crashes manually either by calling the Crash Analytics JavaScript tracker methods directly from the application or by using Matomo Tag Manager.

This guide explains how to implement manual crash reporting with Matomo Tag Manager.

Before you start

Ensure the following prerequisites are in place:

• The Matomo Tag Manager container is installed on your website and successfully tracks pageviews using a Pageview trigger.
• Crash Analytics is enabled in your Matomo instance.
• Your application can detect the error and push the required error details to the Matomo Tag Manager data layer.

Configure Matomo Tag Manager

When your application detects or handles an error, push the error details to the _mtm data layer from the same code that detects or handles the error. Matomo Tag Manager can then listen for the custom event and send the details to Crash Analytics.

In the following example, the application checks a payment response. If it receives an unexpected status, it pushes a crash_analytics_error event before continuing with its error-handling logic:

if (response.status === "UNKNOWN") {
  window._mtm = window._mtm || [];
  window._mtm.push({
    event: "crash_analytics_error",
    crashMessage: "Unexpected payment status returned",
    crashType: "PaymentError",
    crashCategory: "Checkout",
    crashStack: ""
  });

  showPaymentError();
}

For a caught JavaScript exception, place the data layer push inside the catch block:

try {
  processPayment();
} catch (error) {
  window._mtm = window._mtm || [];
  window._mtm.push({
    event: "crash_analytics_error",
    crashMessage: error.message,
    crashType: error.name,
    crashCategory: "Checkout",
    crashStack: error.stack
  });

  showPaymentError();
}

This ensures Matomo Tag Manager receives the actual error details at the moment the application detects or handles the problem.

Add Data Layer variables

1. Open the Tag Manager container and go to Variables.
2. Using the example above, create the following Data Layer variables:
   • crashMessage
   • crashType
   • crashCategory
   • crashStack
3. Click Create New Variable, provide a unique name and the correct Data layer variable name.
4. Click Save and repeat the steps to create all required data layer variables.

Create a Custom Event trigger

1. Go to Triggers and click Create New Trigger.
2. Choose the Custom Event trigger type.
3. Provide a unique trigger name and specify the Event Name. In the example, the event name is crash_analytics_error.
4. Click Save.

Create a Custom HTML tag

1. Go to Tags and click Create New Tag.
2. Choose the Custom HTML tag type.
3. Provide a unique name and add the code (example below) in the Custom HTML field to report the crash.
4. Assign the newly-created custom event trigger (crash_analytics_error) to the Custom HTML tag.

<script>
_paq.push([
    "CrashAnalytics::trackCrash",
    "{{crashMessage}}",
    "{{crashType}}",
    "{{crashCategory}}",
    "{{crashStack}}"
]);
</script>

Test the tracking setup

Use the Preview / Debug mode to test crash tracking. Trigger a test error, and verify that the crash appears in the Crash Analytics Real-time reports.

Troubleshooting

If crash reports do not appear in Crash Analytics, check the following:

• Verify the application pushes the event. Trigger the error and use your browser’s developer tools > Console tab and enter _mtm to confirm that the crash_analytics_error event is added to the _mtm data layer.
• Check the Tag Manager components are firing correctly. In Preview / Debug mode, ensure each variable relevant to your setup resolves to the expected value.
• Verify the Custom Event trigger and Custom HTML tag fire.
• Confirm the _paq.push(["CrashAnalytics::trackCrash", ...]) call executes without JavaScript errors.
• If your site requires tracking consent and consent has not been granted, Crash Analytics does not collect crash reports.
• Confirm that Crash Analytics is enabled in Matomo.
• Check the browser console for errors that may prevent the data layer push.

For examples of manually reporting crashes directly from your application’s code, see the Crash Analytics developer documentation.