Installation

The Permutive JavaScript SDK can be installed using several methods. Choose the approach that best fits your deployment workflow.

Installation Methods

Script Tag (Recommended)
Google Tag Manager
Other Tag Managers

The script tag method is the recommended approach for most websites. It provides the fastest load time and simplest setup.

Basic Installation

Add to the <head> section of your page, as early as possible:

<script>
  !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>",{});
</script>
<script async src="https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js"></script>

Replace:

<WORKSPACE_API_KEY> - Your public API key
<WORKSPACE_ID> - Your workspace ID
<ORGANIZATION_ID> - Your organization ID

Place the SDK script before any other scripts that depend on it (like ad scripts or analytics). The SDK uses a queue-based pattern so methods can be called immediately, but the actual SDK must load before events are sent.

With Configuration Options

Pass configuration options as the fourth argument:

<script>
  !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>",{
    consentRequired: true      // Require consent before tracking
  });
</script>
<script async src="https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js"></script>

Use GTM when you need to manage tags centrally without code deployments.

Setup Steps

Create a Custom HTML Tag
- Go to Tags > New > Custom HTML
- Name it “Permutive SDK”

Add the SDK Code

<script>
  !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"{{Permutive API Key}}","{{Permutive Workspace ID}}",{});
</script>
<script async src="https://{{Permutive Organization ID}}.edge.permutive.app/{{Permutive Workspace ID}}-web.js"></script>

Create Variables (optional but recommended)
- Go to Variables > User-Defined Variables > New
- Create Constant variables for API Key and Workspace ID
- Reference them as {{Permutive API Key}} and {{Permutive Workspace ID}}
Set the Trigger
- Use “All Pages” trigger
- Set Tag Firing Priority to a high number (e.g., 9999) to ensure it loads first

Create Web Addon Tag

<script>
  permutive.addon('web', {
    page: {
      type: '{{Page Type}}',
      article: {
        title: '{{Page Title}}',
        categories: {{Page Categories}}
      }
    }
  });
</script>

For detailed GTM setup including Data Layer integration, see the Tag Manager Guide.

Tealium

Create a JavaScript Code extension
Set execution order to “Before Load Rules”
Add the SDK code with Tealium data layer variables

Adobe Launch

Create a Core extension action for Custom Code
Place in the <head> using the Document section
Set rule order to 1 (earliest execution)

See the Tag Manager Guide for detailed instructions for each platform.

Understanding the Loader Script

The inline loader script (the first <script> block) does the following:

Creates the global permutive object if it doesn’t exist
Initializes a queue (permutive.q) to store method calls before the SDK loads
Sets configuration including API key and workspace ID
Creates stub methods (track, identify, etc.) that add calls to the queue

This pattern allows you to call SDK methods immediately without waiting for the SDK to load. Calls are queued and executed in order once the SDK initializes.

// These calls work immediately, even before live.js loads
permutive.identify([{ tag: 'email_sha256', id: 'abc123...' }]);
permutive.track('PageView', { category: 'news' });
permutive.addon('web', { page: { type: 'article' } });

SDK Source Files

The SDK is served from your organization’s edge CDN:

https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js

The SDK is served from Permutive’s edge CDN with appropriate caching headers. It typically loads in under 100ms on modern connections.

Load Order Best Practices

Load Permutive First

Place the Permutive script tag before other third-party scripts, especially before ad scripts.

Use Async Loading

The async attribute on the live.js script allows parallel loading without blocking page render.

Initialize Web Addon Early

Call permutive.addon('web', {...}) immediately after the SDK script to capture the pageview event early.

Configure Consent Before Tracking

If using consent management, call permutive.consent() before initializing the web addon if consentRequired: true.

Verifying Installation

After installation, verify the SDK is loading correctly:

Add ?__permutive.loggingEnabled=true to your URL
Open the browser console (F12 > Console)
Look for [Permutive] prefixed messages
Check Application > Local Storage for permutive-* keys

Troubleshooting Installation

SDK not loading

Symptoms: No permutive object on window, no console messages.Solutions:

Verify the script URL is correct (https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js)
Check for network errors in DevTools > Network tab
Ensure the inline loader script runs before the SDK script
Check for Content Security Policy (CSP) blocking the script

Methods not working

Symptoms: Calls to permutive.track() or other methods don’t do anything.Solutions:

Verify API key and workspace ID are correct
Check browser console for error messages
Ensure the loader script created stub methods correctly

Script blocked by CSP

Symptoms: Console error about Content Security Policy, or network requests from the SDK fail with stack traces that start with blob:.Solution: Add the Permutive domains and blob: to your CSP:

script-src 'self' https://*.permutive.app;
worker-src 'self' blob:;
connect-src 'self' blob: https://*.permutive.com https://*.permutive.app;

The SDK creates a web worker from a blob: URL and sends network requests from that worker. If your CSP does not allow blob:, the browser blocks the worker or its requests.

Tag manager timing issues

Symptoms: Events missing or SDK not initialized when other tags fire.Solutions:

Set Permutive tag priority to highest (e.g., 9999 in GTM)
Use permutive.ready() in dependent tags to wait for SDK
Ensure trigger fires on “All Pages” before other triggers

Next Steps

Initialization

Configure SDK options

Verification

Verify your integration

Get Started

Products

Deployment

Governance

Installation Methods

Basic Installation

With Configuration Options

Setup Steps

Tealium

Adobe Launch

Understanding the Loader Script

SDK Source Files

Load Order Best Practices

Verifying Installation

Troubleshooting Installation

Next Steps

Initialization

Verification

​Installation Methods

​Basic Installation

​With Configuration Options

​Setup Steps

​Tealium

​Adobe Launch

​Understanding the Loader Script

​SDK Source Files

​Load Order Best Practices

​Verifying Installation

​Troubleshooting Installation

​Next Steps

Initialization

Verification

Installation Methods

Basic Installation

With Configuration Options

Setup Steps

Tealium

Adobe Launch

Understanding the Loader Script

SDK Source Files

Load Order Best Practices

Verifying Installation

Troubleshooting Installation

Next Steps