Skip to main content
The SDK initializes automatically when the live.js script loads. Configuration options are passed in the loader script and control SDK behavior.

​
Basic Initialization

The standard initialization passes your credentials and optional configuration: 
<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>

​
Configuration Options

Pass configuration options as the fourth argument to the loader function: 
!function(e,o,n,i){/* ... */}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>", {
  // Configuration options here
  consentRequired: false,
  loggingEnabled: false
});

​
Available Options

OptionTypeDefaultDescription
consentRequiredbooleanfalseWhen true, SDK waits for consent before tracking
loggingEnabledbooleanfalseEnable console logging (also enabled via ?permutive_debug=true)
cookieDomainstringCurrent domainDomain for the Permutive cookie
requestTimeoutnumber5000API request timeout in milliseconds
When consentRequired: true, the SDK will not track any events until consent is granted: 
<script>
  !function(e,o,n,i){/* ... */}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>", {
    consentRequired: true
  });
</script>
<script async src="https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js"></script>

<script>
  // SDK is loaded but not tracking
  // Events will be ignored until consent is granted

  // When user consents:
  permutive.consent({ opt_in: true, token: '<CONSENT_TOKEN>' });

  // Now initialize the web addon
  permutive.addon('web', {
    page: { type: 'article' }
  });
</script>
With consentRequired: true, all tracking is blocked until permutive.consent() is called with opt_in: true. Events called before consent are not queued - they are discarded.

​
Web Addon Configuration

The web addon is initialized separately and handles automatic tracking. Call it after the SDK loads: 
permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      title: 'Article Title',
      categories: ['news', 'technology'],
      authors: ['John Smith'],
      publishedAt: '2024-01-15T10:00:00Z'
    }
  }
});

​
Web Addon Options

OptionTypeDescription
pageobjectCustom page properties to include in Pageview events
page.typestringPage type (e.g., ‘article’, ‘homepage’, ‘section’)
page.articleobjectArticle-specific metadata
page.videoobjectVideo-specific metadata
eventIntervalnumberMilliseconds between PageviewEngagement events (default: 5000)
contextobjectOverride default context (title, URL, referrer)

​
Page Property Examples

permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      title: 'Breaking News: Tech Advances',
      id: 'article-123',
      categories: ['technology', 'business'],
      tags: ['AI', 'startups', 'innovation'],
      authors: ['Jane Smith', 'John Doe'],
      publishedAt: '2024-01-15T10:00:00Z',
      modifiedAt: '2024-01-15T14:30:00Z',
      premium: true,
      wordCount: 1500
    }
  }
});

​
Waiting for SDK Ready

Use permutive.ready() to execute code after the SDK initializes: 
// Wait for SDK initialization
permutive.ready(function() {
  console.log('Permutive SDK is ready');

  // Safe to access cohorts, etc.
  permutive.segments(function(segments) {
    console.log('User cohorts:', segments);
  });
});

​
Ready Stages

The ready() method accepts an optional stage parameter: 
// Default: Wait for basic initialization
permutive.ready(function() {
  // SDK initialized, can track events
}, 'initialised');

// Wait for real-time cohort data
permutive.ready(function() {
  // Real-time cohort data is available
  permutive.segments(function(segments) {
    // segments array is populated
  });
}, 'realtime');
StageWhen Fires
initialisedSDK has loaded and initialized (default)
realtimeReal-time cohort data has been processed

​
Initialization Order

For optimal performance, follow this initialization order:
1

Loader Script

The inline loader script runs first, creating the queue and stub methods.
2

Consent (if required)

If using consentRequired: true, call permutive.consent() after obtaining user consent.
3

Identify (if available)

If you have user identity (e.g., logged-in user), call permutive.identify() early.
4

Web Addon

Initialize the web addon to start tracking pageviews and engagement.
5

Other Addons

Initialize other addons (DFP, Prebid, etc.) after the web addon.

​
Example: Complete Initialization

<!DOCTYPE html>
<html>
<head>
  <!-- 1. SDK Loader -->
  <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>

  <!-- 2. Set identity if available -->
  <script>
    if (window.userEmail) {
      permutive.identify([
        { tag: 'email_sha256', id: hashSHA256(window.userEmail) }
      ]);
    }
  </script>

  <!-- 3. Initialize web addon -->
  <script>
    permutive.addon('web', {
      page: {
        type: 'article',
        article: {
          title: document.title,
          categories: window.pageCategories || []
        }
      }
    });
  </script>
</head>
<body>
  <!-- Page content -->
</body>
</html>
The SDK uses a first-party cookie to persist user identity. Configure the cookie domain for cross-subdomain tracking: 
!function(e,o,n,i){/* ... */}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>", {
  cookieDomain: '.example.com'  // Shared across subdomains
});
Set cookieDomain to your root domain (with leading dot) to track users across subdomains like www.example.com and blog.example.com.

​
Environment Configuration

For testing environments, you may want different configurations: 
var config = {
  loggingEnabled: window.location.hostname !== 'www.example.com'
};

!function(e,o,n,i){/* ... */}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>", config);

​
Troubleshooting Initialization

Problem: No console messages, permutive.ready() callback never fires.Solutions:
  • Check that API key and workspace ID are correct
  • Verify live.js is loading (check Network tab)
  • Look for errors in the console
  • Ensure the loader script runs before live.js
Problem: Events are called but nothing appears in dashboard.Cause: consentRequired: true but consent() was not called.Solution: Call permutive.consent({ opt_in: true, token: '...' }) after obtaining user consent.
Problem: SDK initializes but no Pageview events.Solutions:
  • Verify permutive.addon('web', {...}) is called
  • Check that consent has been granted (if consentRequired: true)
  • Enable debug mode to see detailed logging
Problem: Calling segments() in ready() callback returns empty array.Solution: Use the 'realtime' stage:
permutive.ready(function() {
  permutive.segments(function(s) {
    console.log(s);  // Now populated
  });
}, 'realtime');

​
Next Steps

Verification

Verify your integration is working

Pageview Tracking

Customize pageview tracking