JavaScript SDK

Quick Start

Features

Integrations

Issues

Overview

The Permutive JavaScript SDK enables user segmentation, personalization, and ad targeting on your website. Track user behavior, manage identities, and deliver targeted advertising through integrations with major ad platforms including Google Ad Manager, Prebid.js, and Xandr. Current Version: See your Permutive dashboard for the latest version.

Browser Support: The SDK supports all modern browsers including Chrome, Firefox, Safari, and Edge. It is designed to work in environments without third-party cookies.

Getting Started

New to the Permutive JavaScript SDK? Start here.

Quick Start Guide

Get up and running with your first pageview in minutes

Installation

Script tag and tag manager installation options

Initialization

SDK initialization and configuration options

Verification

Verify your integration is working correctly

Core Concepts

Understand the fundamental concepts of the Permutive SDK.

Identity Management

Track users across sessions and devices

Event Properties

Structure and validate event data

Cohorts and Activations

Understanding user segmentation

Contextual Data

Content-based real-time targeting

Consent Management

GDPR, TCF, and consent handling

Features

Detailed guides for specific SDK features.

Pageview Tracking

Automatic and manual pageview tracking with the web addon

Event Tracking

Track custom events with track(), on(), and once()

Video Tracking

Track video content viewing

Real-Time Triggers

React to cohort changes with trigger(), segment(), and query()

Integrations

Connect Permutive with ad platforms and header bidding solutions.

View All Integrations

Google Ad Manager, Prebid.js, Xandr, and more

Common Tasks

Track a Pageview

The web addon automatically tracks pageviews when configured. You can also include custom page properties.

permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      title: 'Breaking News: Tech Advances',
      categories: ['technology', 'news'],
      authors: ['Jane Smith'],
      publishedAt: '2024-01-15'
    }
  }
});

Track a Custom Event

permutive.track('Purchase', {
  product_id: 'SKU123',
  product_name: 'Premium Subscription',
  price: 9.99,
  currency: 'USD'
});

Set User Identity

// Simple identity
permutive.identify([
  { tag: 'email_sha256', id: 'a1b2c3d4e5f6...' },
  { tag: 'internal_id', id: 'user_12345', priority: 1 }
]);

React to Cohort Changes

// Check if user is in a specific cohort
permutive.segment(12345, function(inCohort) {
  if (inCohort) {
    showPremiumContent();
  }
});

// Get all cohorts
permutive.segments(function(segments) {
  console.log('User cohorts:', segments);
});

Target Google Ads

// Using the DFP addon (automatically sets targeting)
permutive.addon('web', { page: { /* ... */ } });

// Or manually get segments for GPT
permutive.segments(function(segments) {
  googletag.cmd.push(function() {
    googletag.pubads().setTargeting('permutive', segments);
  });
}, 'dfp');

Key API Methods

Method	Purpose
`permutive.track(event, properties)`	Track custom events
`permutive.identify(identities)`	Set user identities
`permutive.trigger(code, param, handler)`	React to cohort entry/exit
`permutive.segment(code, handler)`	Check single cohort membership
`permutive.segments(handler, type)`	Get all cohorts
`permutive.query(code, handler)`	Reserved for future use
`permutive.ready(callback, stage)`	Wait for SDK initialization
`permutive.consent(data)`	Set consent status
`permutive.addon(name, options)`	Initialize addons
`permutive.on(event, callback)`	Persistent event listener
`permutive.once(event, callback)`	Single event listener
`permutive.reset()`	Clear user data

Requirements

Requirement	Details
Browsers	Modern browsers (Chrome, Firefox, Safari, Edge)
JavaScript	ES5+ (SDK is transpiled for compatibility)
Cookies	First-party cookies required for identity persistence
localStorage	Required for cohort storage

Installation

Script Tag (Recommended)
Tag Manager

Add to the <head> of your page, 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>

Replace <WORKSPACE_API_KEY>, <WORKSPACE_ID>, and <ORGANIZATION_ID> with your credentials from the Permutive dashboard.

Key Concepts

Queue-Based Loading

The SDK uses a queue-based loading pattern. Methods called before the SDK loads are queued and executed in order once the SDK initializes. This means you can safely call SDK methods immediately without waiting for load.

Cohorts vs. Activations

Cohorts: All segments a user belongs to
Activations: Cohorts configured for specific ad platforms (e.g., dfp for Google Ad Manager)

Behavioral vs. Contextual

Behavioral: Based on user history (e.g., “sports enthusiast”)
Contextual: Based on current page content (e.g., viewing sports article right now)

Web Addon

The web addon provides automatic tracking for pageviews, engagement time, form submissions, and link clicks. It’s the recommended way to track user activity.

Additional Resources

Guides
Reference

Tag Manager Setup - GTM, Tealium, Adobe Launch
Single Page Applications - React, Vue, Angular integration

FAQ

Does the SDK work without third-party cookies?

Yes. The Permutive SDK uses first-party cookies and localStorage, which are not affected by third-party cookie restrictions. It works effectively in Safari, Firefox, and other browsers that block third-party cookies.

How do I enable debug logging?

Add ?permutive_debug=true to any page URL to enable debug logging in the browser console. You’ll see detailed information about events, cohorts, and SDK activity.

What's the difference between track() and the web addon?

The web addon automatically tracks standard events (Pageview, PageviewEngagement, FormSubmission, LinkClick) with minimal configuration. Use track() for custom events that don’t fit these patterns.

How do I handle consent/GDPR?

Does the SDK support Single Page Applications?

Yes. The web addon provides a reset() method for SPA navigation. Call it when the route changes to track new pageviews. See Pageview Tracking for details.

Getting Help

Troubleshooting Guide - Solutions to common issues
Customer Success Manager - Your primary contact
Technical Services - Technical integration support
Support - Troubleshooting and help

Privacy & Compliance

Permutive is designed with privacy in mind: GDPR compliant, CCPA compliant, no PII storage, user consent respected, and transparent data usage.

Get Started

Products

SDKs

Governance

Quick Start

Features

Integrations

Issues

Overview

Getting Started

Quick Start Guide

Installation

Initialization

Verification

Core Concepts

Identity Management

Event Properties

Cohorts and Activations

Contextual Data

Consent Management

Features

Pageview Tracking

Event Tracking

Video Tracking

Real-Time Triggers

Integrations

View All Integrations

Common Tasks

Key API Methods

Requirements

Installation

Key Concepts

Additional Resources

FAQ

Getting Help

Privacy & Compliance

Get Started

Products

SDKs

Governance

Quick Start

Features

Integrations

Issues

​Overview

​Getting Started

Quick Start Guide

Installation

Initialization

Verification

​Core Concepts

Identity Management

Event Properties

Cohorts and Activations

Contextual Data

Consent Management

​Features

Pageview Tracking

Event Tracking

Video Tracking

Real-Time Triggers

​Integrations

View All Integrations

​Common Tasks

​Key API Methods

​Requirements

​Installation

​Key Concepts

​Additional Resources

​FAQ

​Getting Help

​Privacy & Compliance

Overview

Getting Started

Core Concepts

Features

Integrations

Common Tasks

Key API Methods

Requirements

Installation

Key Concepts

Additional Resources

FAQ

Getting Help

Privacy & Compliance