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>
<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_debug=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
