Quick Start

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

Enable Debug Mode: Add ?__permutive.loggingEnabled=true to your page URL
Open Developer Console: Press F12 or right-click and select “Inspect”, then go to the Console tab

Look for SDK Messages: You should see messages like:

[Permutive] SDK initialized
[Permutive] Pageview tracked

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

Get Started

Products

Deployment

Governance

Prerequisites

Step 1: Add the SDK

Step 2: Initialize the Web Addon

Step 3: Complete Example

Step 4: Verify the Integration

What Happens Automatically

Next Steps

Installation Details

Initialization Options

Pageview Tracking

Identity Management

​Prerequisites

​Step 1: Add the SDK

​Step 2: Initialize the Web Addon

​Step 3: Complete Example

​Step 4: Verify the Integration

​What Happens Automatically

​Next Steps

Installation Details

Initialization Options

Pageview Tracking

Identity Management

Prerequisites

Step 1: Add the SDK

Step 2: Initialize the Web Addon

Step 3: Complete Example

Step 4: Verify the Integration

What Happens Automatically

Next Steps