Skip to main content
This guide walks you through adding the SDK to your page and tracking your first pageview.

​
Prerequisites

  • Your Permutive Workspace API Key, Workspace ID, and Organization ID (from your dashboard)
  • Access to edit your website’s HTML or tag manager

​
Step 1: Add the SDK

Add the following code to the <head> section of your page, as early as possible. This ensures the SDK loads before other scripts and can queue events immediately. 
<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>, <WORKSPACE_ID>, and <ORGANIZATION_ID> with your credentials from the Permutive dashboard.
Queue-Based Loading: The SDK uses a queue-based pattern. You can call SDK methods immediately - they’re queued and executed once the SDK loads.

​
Step 2: Initialize the Web Addon

The web addon provides automatic pageview tracking, engagement measurement, and more. Add this code after the SDK script: 
<script>
  permutive.addon('web', {
    page: {
      type: 'article',
      article: {
        title: document.title,
        categories: ['technology'],
        authors: ['Jane Smith']
      }
    }
  });
</script>
Customize the page object with your content metadata. This enables contextual targeting and richer insights.

​
Step 3: Complete Example

Here’s a complete example with the SDK, web addon, and page properties: 
<!DOCTYPE html>
<html>
<head>
  <title>My Article</title>

  <!-- Permutive SDK - Load 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>

  <!-- Initialize Web Addon -->
  <script>
    permutive.addon('web', {
      page: {
        type: 'article',
        article: {
          title: 'Breaking News: Tech Advances',
          categories: ['technology', 'news'],
          authors: ['Jane Smith'],
          publishedAt: '2024-01-15'
        }
      }
    });
  </script>
</head>
<body>
  <!-- Your page content -->
</body>
</html>

​
Step 4: Verify the Integration

  1. Enable Debug Mode: Add ?__permutive.loggingEnabled=true to your page URL
  2. Open Developer Console: Press F12 or right-click and select “Inspect”, then go to the Console tab
  3. Look for SDK Messages: You should see messages like: 
    [Permutive] SDK initialized
[Permutive] Pageview tracked
  4. Check localStorage: In Developer Tools, go to Application > Local Storage and look for keys starting with permutive- or _p
If you see “Permutive SDK initialized” and “Pageview tracked” messages, your integration is working correctly.

​
What Happens Automatically

With the web addon configured, the SDK automatically:
  • Tracks Pageview events when the page loads
  • Measures engagement time (PageviewEngagement events)
  • Tracks page completion (PageviewComplete when user leaves)
  • Captures form submissions (FormSubmission events)
  • Records link clicks (LinkClick events for outbound links)

​
Next Steps

Installation Details

Tag manager options

Initialization Options

Advanced SDK configuration

Pageview Tracking

Customize pageview tracking

Identity Management

Track users across sessions