We are excited to announce a new update that enhances our security capabilities: support for custom Trusted Types policies. This allows developers to specify their own Trusted Types policies, providing them more flexibility and control over how content is handled within their applications.
What are Trusted Types policies?
Trusted Types are a browser-enforced web security feature designed to prevent cross-site scripting (XSS) attacks. It works by locking down dangerous web APIs and requiring that any content passed to these APIs is first processed through a trusted policy. This helps to mitigate the risk of malicious code execution.
Introducing Custom Trusted Types
Previously, Microsoft Clarity only supported the default Trusted Types policy. With this update, developers can now specify a custom Trusted Types policy by adding an optional parameter to the Clarity tag request in the setup code:
https://www.clarity.ms/tag/<ProjectId>?trustedTypes=<PolicyName> This enhancement allows you to define and enforce your own security policies, tailored to the specific needs of your application.
What Are the Benefits of Custom Trusted Types?
If you’re a developer responsible for implementing Clarity on your site, this feature gives you a way to integrate session recording and analytics without compromising on frontend security. Here’s why it matters:
Enhanced Security
By defining custom policies, you can ensure that only sanitized and validated content is executed, reducing the risk of XSS attacks.
Flexibility
Custom policies allow you to specify different handling mechanisms for various types of content, such as HTML, scripts, and URLs.
Compliance
Custom policies help you meet high security requirements and standards, ensuring that your application adheres to best practices.
How to Set Up Trusted Types
Want to start using a custom Trusted Types policy with Clarity? Here’s how to do it in two steps.
Create a Trusted Types Policy
Use trustedTypes.createPolicy() to define your custom policy:
For example:
const ClarityPolicy = trustedTypes.createPolicy('ClarityPolicy', {
createScriptURL: (input) => {
if (input.startsWith('https://www.clarity.ms')) {
return input;
}
throw new Error('Untrusted URL');
}
}); Update the Clarity Tag
Add the trustedTypes parameter to your Clarity tag request:
<script type="text/javascript">
(function(c,l,a,r,i,t,y){
c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i+"?trustedTypes=ClarityPolicy";
y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "<ProjectId>");
</script> Note: If Trusted Types are not supported by the browser, the script will fall back to its default behavior of adding the script directly.
Conclusion
With support for custom Trusted Types policies, Clarity gives developers more security without compromising functionality. Whether you’re building for compliance, scaling a high-traffic site, or simply aiming for best-in-class web security, this feature helps you stay in control.
Want to dive deeper into how Trusted Types work? Check out MDN’s Trusted Types documentation for more technical guidance.