Script Injection Feature

9 min

What is this feature?

This feature allows you to load scripts (e.g., for ad servers or other custom integrations) in the head of your website without using the purple plugin system. These scripts load quickly when users visit your pages and work correctly with the website's architecture.

It is your responsibility to properly trigger their execution, and you must make sure they comply with consent requirements.

The script injection feature is available from PXP 5.0.0. Please refer to Software Version for further info on what version is avalable at which domain.

Why do we need this?

Fast Loading: Critical scripts load immediately when users visit the page

Reliable: Scripts always work correctly regardless of how the page is loaded

Flexible: You can add different types of scripts to different parts of the page

Easy Management: All scripts are managed through configuration

These scripts are not executed during server-side rendering. They are intended for client-side effects like ads.

How to use it?

You can add scripts to your website by updating the experience-config.json There are two places where you can add scripts:

Adding Scripts to Page Header

Scripts added here load first and are best for critical functionality:

{
  "purple": {
    "scripts": {
      "head": [
        {
          "src": "https://example.com/important-script.js"
        }
      ]
    }
  }
}

Adding Scripts to Page Body

Scripts added here load after the main content:

{
  "purple": {
    "scripts": {
      "body": [
        {
          "src": "https://example.com/analytics-script.js"
        }
      ]
    }
  }
}

Each script object can contain any HTML script attributes. The structure under head and body contains objects where each property becomes an attribute of the <script> tag:

i.e.:

{
  "purple": {
    "scripts": {
      "head": [
        {
          "src": "https://example.com/script.js",
          "async": "",
          "defer": null,
          "type": "text/javascript",
          "data-custom": "my-value"
        }
      ]
    }
  }
}

Multiple Scripts

You can add multiple scripts at once:

{
  "purple": {
    "scripts": {
      "body": [
        {
          "src": "https://script1.com"
        },
        {
          "src": "https://script2.com"
        },
        {
          "src": "https://script3.com"
        }
      ]
    }
  }
}

Using Local Script Files

You can also load scripts from the project dynamic resources using the resource://dynamic/ prefix:

{
  "purple": {
    "scripts": {
      "head": [
        {
          "src": "resource://dynamic/storefront/assets/my_script.js"
        }
      ]
    }
  }
}

Best Practices

When to Use Header vs Body

Use Header for critical scripts that need to load first (consent management, essential tracking)

Use Body for non-critical scripts (analytics, social media widgets)

Script Loading Tips

Add one script at a time and test it

Check browser console for any error messages

Test on different devices and browsers

This feature was made for the use in Websites, for instance. There might be side effects in Apps, so if you want to use this on a project that includes Websites and apps, make sure to test the behavior early on to ensure proper behavior.