Preview / debug a tag manager container

Cloud On-Premise

Matomo Tag Manager provides a Preview / Debug mode that enables the testing of tags, triggers, and variables before publishing changes. This helps you to verify the container behaves as expected and identify configuration issues before applying it to your live website.

When using this mode, Matomo creates a preview (draft version) of your container. This preview container is automatically updated each time you save a change, allowing you to immediately test your latest configuration without publishing it to your live website.

Enable Preview / Debug mode

  1. Open the container in Matomo Tag Manager and click the Preview / Debug option.
    click on preview debug mode

  2. A notification is displayed in the container preview when Preview / Debug mode is enabled.
    enable debug in mtm

  3. Enter your website URL and click Debug to open your website with the debug console enabled.

  4. As you interact with your website, tracked actions and custom events appear in the left pane. Selecting an action or event shows which triggers and tags fired, and the values of any defined variables.
    debug tags in mtm

Manually open or share a preview container

Preview / Debug mode is enabled only for the browser that started the session. If you cannot launch Debug mode directly from Matomo, or you want to share the preview in another browser or with another user, use the debug URL containing the mtmPreviewMode parameter shown in Matomo.

  • If the URL does not contain parameters, append the following to view debug mode:
    ?mtmPreviewMode=YOUR_CONTAINER_ID
  • If the URL already contains query parameters, append this parameter instead to the URL: &mtmPreviewMode=YOUR_CONTAINER_ID. 
https://example.com/page?category=products&mtmPreviewMode=YOUR_CONTAINER_ID&mtmSetDebugFlag=1
  • Add &mtmSetDebugFlag=1 to display the debug console.

Temporarily disable Preview / Debug mode

To temporarily load the published container instead of the preview container, append ?mtmPreviewMode=0 (or &mtmPreviewMode=0 if the URL already contains query parameters). This lets you switch between the published and preview containers without disabling Preview / Debug mode in Matomo.

Next steps

The debug console helps you diagnose configuration issues and confirm that tags fire under the correct conditions. Once you have confirmed that your container works correctly, return to the container dashboard and publish the container to the live environment.