Content Security Policies (CSPs)

This page explains what you'll need to do to use Conductrics Express (or our browser-side JavaScript API) on web pages that use a [Content Security Policy] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) (CSP).

📘

These instructions are only relevant if your site implements a strict Content Security Policy, and you're using client-side Conductrics functionality such as Conductrics Express or our in-browser JavaScript API. They don't pertain to our REST API.

CSP / Nonce Checklist

Here's what you'll need to do:

1. Allow the Conductrics script to be included on your page. You can use the CSP script-src or script-src-elem directives for this. See the next section for details.
2. Allow the script to send event messages back to Conductrics so that we can update our reporting numbers. You can use the CSP connect-src directive for this. See the section below for details.
3. If you want to use the "WYSIWYG" editing mode for setting up variations, you also need to allow Conductrics to add the editing panels to your pages. Note that if you have a separate staging or QA type environment, you would only need to allow the editing mode to work in that environment, not your production environment.

See the following sections for details.

Getting Required CSP Info

1. Go to Settings > Deploy Targets in the Conductrics Admin.
2. Hit the Get JS Tag button for your Deploy Target.
3. Go to the CSP Info to get the values to add to your Content-Security-Policy header.

Using the CSP "Checker"

The Conductrics Admin contains a simple "CSP Checker" which you can use to verify that the required entries have been added to your CSP.

1. Go to Settings > Deploy Targets in the Conductrics Admin.
2. Hit the Get JS Tag button for your Deploy Target.
3. Under the CSP Checker tab, paste in a page URL and hit the Check button as shown below.

Here's what that looks like if you provide a URL for a page that has a CSP, but where the required entries have not been added:

Once the required entries have been added, the red "X" icons above would turn to green "Checks".

📘

Please note that the CSP Checker tool may not successfully validate every possible CSP scenario (for instance a CSP that whitelists the Conductrics script at one level, but then denies it at a different level). Feel free to contact Conductrics if you have any questions.

Reviewing your Current CSP Manually

You can also find your current CSP "manually", using your browser:

1. Open up your browser's Developer Tools and find the Network tab (it is probably empty if you just opened your Developer Tools).
2. Reload the page, which should populate the Network tab.
3. Click on the entry for the page itself (as opposed to the various scripts and images and so on), which is probably the first entry in the list.
4. Look at the headers for the page, and find the Content-Security-Policy header. The CSP you're looking at is the same thing that browser is using to determine whether a given third-party asset (such as the Conductrics script tag) is "allowed" on your site.

📘

Quick Tip: Some CSP headers are long and hard to read as-is. You may find it easier to copy-and-paste the header into a text editor for easier viewing. You can use the search-and-replace in your text editor to add a couple of newlines after each semicolon. That will make it a lot easier to read.

Once you can view the CSP, you can check whether it has the required entries for Conductrics:

• Does the CSP have ascript-src or script-src-elem entry to allow the Conductrics script tag? You can get the expected value from the CSP Info tab as discussed above. See also the How to embed the Conductrics script with a nonce and How to embed the Conductrics script without a nonce sections below.
• Does the CSP have aconnect-src entry to allow event messages back to Conductrics? You can get the expected value from the CSP Info tab as discussed above. See also the Allowing event messages to be passed back to Conductrics section below for details.
• If you want to use the WYSIWYG editing mode on the pages in question, does the CSP have frame-src, script-src-elem, and style-src entries to allow our editing tools to be added to the page? You can get the expected value from the CSP Info tab as discussed above. See also the If you plan on using the "WYSIWYG" editing mode section below for details.

There are also browser extensions available for most browsers to make it easier to view your CSP.

📘

While less typical, your site could provide its CSP via a <meta> tag in your page's HTML (as opposed to in an HTTP header as discussed above). So, if you don't see a Content-Security-Policy header at all, it's worth checking if there's a <meta> tag with http-equiv="Content-Security-Policy" in your page HTML. See the notes about the <meta> tag usage at the MDN doc page about CSPs.

How to embed the Conductrics script with a nonce

Let's say you have the following Conductrics script tag, which you've gotten from our admin:

<script src="https://cdn-v3.conductrics.com/ac-example/v3/agent-api/js/site-1/dt-example-0123?apikey=api-9999999"></script>

When adding it to your page, all you need to do is add a nonce attribute that matches the generated nonce from your CSP header (the nonce might be provided in the script-src, script-src-elem, or default-src directives).

So, let's say that for a particular page view, the Content-Security-Policy header from your servers looks like this:

Content-Security-Policy: script-src 'nonce-example-12345';

The above uses a script script-src directive for clarity, but you may want to use script-src-elem instead or in addition, depending on whether you are targeting browsers that support CSP Level 2 or 3. In any case, you now need to provide the same value to the nonce attribute for the