Embedding external JavaScript into the application

Owned by Felix Bauer
Last updated: Dec 18, 2024
3 min read

To connect certain 3rd party tools, a custom JavaScript must be executed in the browsers of the visitors of the 3YOURMIND application.

Examples are:

  • Google Analytics or other tracking tools

  • A cookie banner

  • A support widget

  • A chatbot

Steps

Two steps are necessary to embed an external JavaScript into the application:

  1. Add external domains to the CSP Header

  2. Add the script to the admin panel

Add external domains to the CSP Header

3YOURMIND has a Content Security Policy in place that protects against certain forms of cybersecurity attacks. Its default settings disallow loading content from any domain that is not part of the policy.

If you skip this step then you will see the following error in the browser's JavaScript console:

Refused to load the script '[domain]' because it violates the following Content Security Policy directive: "script-src 'self' 'unsafe-inline' 'unsafe-eval' google.com *.amazonaws.com *.gstatic.com *.stripe.com *.stripe.network pagecdn.io". Note that 'script-src-elem' was not explicitly set, so 'script-src' is used as a fallback.

To add a domain to the list of allowed domains, you must add the following content to the values.yaml configuration file. For SaaS installations this can only be done by our Technical Support Team:

serviceConfig: revproxy: extraCspSources: "[List of domains, seperated by whitespace]"

Google Analytics

Due to different versions of Google Analytics (+ combinations with the Tag Manager), it is complicated to add the right domains - expect some trial & error.

Review this resource:

Use Tag Manager with a Content Security Policy  |  Security and Privacy hub  |  Google for Developers

Here is a working example of a Google Tag Manager setting:

extraCspSources: "'unsafe-inline' https://www.googletagmanager.com"

If Google Analytics 4 is used, use the following domains”

Add the script to the admin panel

  • Go to the admin panel (by adding /admin to the domain).

  • There, go to: Organizations > Your Organization

  • Add the script without the <script> tag into the Extra Script box

  • Click on Save

Example:

image-20241210-104646.png

Migrating from the old format

Up to version 24.12, the extra-scripts was interpreted as HTML and contained also <script> tags.

This was changed in 24.12(See 24.12 LTS | Extra Scripts . Now the content of the extra-scripts is interpreted as JavaScript and added to the Document as an external script.

To ensure backwards compatibility, all existing scripts have been wrapped like this: document.write(`[old script]`).

We encourage customers who currently use an extra-script to manually remove the document.write again and transform the existing scripts into plain javascript and css.

 

To do the migration, modify the extra-script as follows:

  1. Make a backup of the existing extra-script.

  2. Remove the document.write(` at the top and the `)at the end

  3. Remove all HTML comments (e.g. <!-- Google Tag Manager --> ) OR convert them into JavaScript Comments: (e.g. // Google Tag Manager )

  4. Remove the <noscript> sections

  5. Change the way external <script>s are called:

    1. From: <script src="[some URL]"></script>

    2. To:

       

  6. If the original call included an async tag change it like this:

    1. From: <script async src="[some URL]"></script>

    2. To:

       

  7. Move the content of the <style> test into the extra-style textarea (ommiting the <style> tag itself)

  8. Remove the remaining <scipt> and </script> tags, keeping the content.

  9. Save and test your changes