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: 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 >
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 existInitializes a queue (permutive.q) to store method calls before the SDK loadsSets configuration including API key and workspace IDCreates 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_debug=true to your URL
Open the browser console (F12 > Console)
Look for [Permutive] prefixed messages
Check Application > Local Storage for permutive-* keys
Troubleshooting Installation
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
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
Symptoms: Console error about Content Security Policy.Solution: Add Permutive domains to your CSP:script-src 'self' https://*.permutive.app; connect-src 'self' https://*.permutive.com https://*.permutive.app;
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 
