Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.permutive.com/llms.txt

Use this file to discover all available pages before exploring further.

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.loggingEnabled=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