Improve MTM Preview + API handling under strict CSP and CORS

[jmumby]

Description

When using Matomo Tag Manager (MTM) with a strict Content Security Policy (CSP) and the Data API from Matomo Cloud, there are two recurring problems:

1. MTM Preview blocked by CSP

• MTM Preview injects inline scripts without inheriting the site’s server-side nonce.

• On sites with CSP like:

  script-src 'self' 'nonce-<…>' https://cdn.matomo.cloud https://<instance>.matomo.cloud

  the preview UI fails, since those inline snippets don’t match the nonce and are blocked.

• Current workarounds:

  • Relax CSP temporarily (unsafe-inline or hash).
  • Run preview on a staging domain with weaker CSP.

Neither is ideal, as it undermines CSP or complicates deployment.

2. CORS failures when calling the API client-side

Example error:

Access to XMLHttpRequest at 'https://<instance>.matomo.cloud/?module=API&…' 
from origin 'https://example.com' has been blocked by CORS policy: 
No 'Access-Control-Allow-Origin' header present.

This makes it impossible to fetch API data directly from the browser.
Current workaround: proxy API calls server-side.

Why this matters

• CSP is increasingly required in enterprise/security-focused environments, so needing unsafe-inline or hashes for preview creates adoption friction.
• Customers expect to be able to test MTM in preview without altering production CSP rules.
• Direct API calls from client-side aren’t supported, but the failure mode isn’t well documented, leading to confusion.

Suggested Improvements

• Preview:

  • Propagate nonces to injected scripts in MTM preview, or serve preview scripts in a way compatible with strict CSP.
  • Alternatively, provide clearer guidance or a preview-specific loader that works with nonce-based CSP.

• API / CORS:

  • Improve documentation that cross-origin API calls are intentionally unsupported.
  • Optionally provide an official proxy endpoint or recommended integration pattern.

Environment

• Matomo Cloud
• Matomo Tag Manager (preview mode)
• Strict CSP with nonce (script-src 'self' 'nonce-…')

[AltamashShaikh]

Good to add a way for users to pass the nonce, so that previewJS loads without any issue.