Skip to main content
Cohorts are the core mechanism for user segmentation in Permutive. The SDK provides methods to check cohort membership and react to changes in real-time.

What are Cohorts

Activations

SDK Methods

​
What are Cohorts

A cohort is a privacy-safe representation of an audience.Traditionally, user IDs like third-party cookies have been used to communicate information about audiences and activate (target) them. A publisher might communicate behavioral data for a user to an ad server by attaching the data to a cookie ID. The ad server uses the cookie ID to record information about the user—both information from the publisher and other data parties they work with—and the ad server can later target an ad for a request from that user based on the information it has attached to their cookie ID.With cohorts, a code represents the group of users that fall into an audience. In the example above, when the publisher requests an ad from the ad server for the user, it includes the cohort code in the request, but not a user ID. The ad server can use the cohort code(s) to decision on the ad to respond with, but no other publisher or user data is leaked and a profile of the user cannot be built.By removing user identifiers from the equation, users' privacy is protected, the publisher's data cannot be targeted off of their site/app, and publishers can provide reachability (scale) to the ecosystem since cohorts can be built & activated in environments like Apple Safari, Mozilla Firefox, and iOS where third-party cookies and other deterministic identifiers are prohibited.

​
Cohort Types

Based on user actions and event patterns tracked through the SDK.Example: A user who reads 5+ sports articles becomes part of the "sports_enthusiast" cohort.
User reads article about tennis
    ↓
Track event: "Pageview" with properties
    ↓
Permutive evaluates: "User read 3+ sports articles in 7 days?"
    ↓
User enters cohort: "sports_enthusiast"

​
How Cohorts Work

  1. Events are tracked via the SDK (pageviews, custom events, etc.)
  2. Rules are evaluated against user behavior
  3. Users enter/exit cohorts based on rule matching
  4. Cohorts are stored locally in the browser
  5. Cohorts are passed to ad platforms for targeting
User views sports article → Track Pageview event
                               ↓
                    Permutive evaluates rules
                               ↓
                    User enters "sports_enthusiast" cohort
                               ↓
                    Cohort stored in localStorage
                               ↓
                    Cohort passed to ad requests

​
Activations

Activations are subsets of cohorts configured for specific ad platforms. Not all cohorts are activated for all platforms—activations allow you to control which cohorts are sent to which ad networks.
  • Platform-specific targeting - Different ad platforms may need different cohorts
  • Data governance - Control which platforms receive which user segments
  • Performance optimization - Only send relevant cohorts to each platform
  • Compliance - Manage consent and privacy requirements per platform

​
Activation Types

Activation TypePlatformUse Case
dfpGoogle Ad ManagerStandard behavioral cohort activations
dfp_contextualGoogle Ad ManagerReal-time contextual cohorts
appnexus_adserverXandr/AppNexusStandard behavioral cohort activations
appnexus_adserver_contextualXandr/AppNexusReal-time contextual cohorts
freewheelFreewheelCTV/video ad targeting

​
Cohorts vs Activations

AspectCohortsActivations
DefinitionAll segments a user belongs toCohorts configured for specific platforms
ScopeEntire Permutive systemPlatform-specific
PurposeUser segmentationAd targeting
ConfigurationAutomatic based on eventsConfigured in dashboard

​
Accessing Cohorts

​
Get All Segments

// Get all cohorts the user belongs to
permutive.segments(function(segments) {
  console.log('All segments:', segments);
  // Output: [12345, 67890, 11111, ...]
});

​
Get Platform-Specific Segments

// Get cohorts activated for Google Ad Manager (DFP)
permutive.segments(function(segments) {
  console.log('DFP segments:', segments);
}, 'dfp');

// Get cohorts activated for AppNexus
permutive.segments(function(segments) {
  console.log('AppNexus segments:', segments);
}, 'appnexus');

​
Check Single Cohort Membership

// Check if user is in a specific cohort
permutive.segment(12345, function(inCohort) {
  if (inCohort) {
    console.log('User is in cohort 12345');
    showPremiumContent();
  } else {
    console.log('User is NOT in cohort 12345');
    showStandardContent();
  }
});

​
Wait for Cohort Data

Use ready() with the 'realtime' stage to ensure cohort data is available: 
permutive.ready(function() {
  // Cohort data is now available
  permutive.segments(function(segments) {
    console.log('Segments (after ready):', segments);
  });
}, 'realtime');

​
Real-Time Triggers

React to cohort changes as they happen: 
// Trigger when user enters/exits a cohort
permutive.trigger(12345, 'result', function(obj) {
  if (obj.result) {
    console.log('User just ENTERED cohort 12345');
  } else {
    console.log('User just EXITED cohort 12345');
  }
});
See Real-Time Triggers for more details.

​
localStorage Structure

Cohorts are stored in localStorage for fast access and ad targeting:
KeyPurpose
_psegsAll cohorts
_pdfpsGoogle Ad Manager (DFP) activations
_papnsAppNexus activations
_prubiconsRubicon activations
_ppubmaticsPubMatic activations
// Direct localStorage access (for debugging)
var allCohorts = JSON.parse(localStorage.getItem('_psegs') || '[]');
var dfpCohorts = JSON.parse(localStorage.getItem('_pdfps') || '[]');
Always use the SDK methods (segments(), segment()) rather than reading localStorage directly in production code. The SDK handles synchronization and edge cases.

​
Using Cohorts with Ad Platforms

// Using the DFP addon (automatic)
permutive.addon('web', { page: { type: 'article' } });
// Targeting is set automatically

// Manual targeting
permutive.segments(function(segments) {
  googletag.cmd.push(function() {
    googletag.pubads().setTargeting('permutive', segments);
  });
}, 'dfp');

​
Prebid.js

Cohorts are automatically passed to Prebid via the RTD module. See Prebid Integration.

​
AppNexus/Xandr

permutive.segments(function(segments) {
  // Use segments for AppNexus targeting
  apntag.setKeywords('permutive', segments);
}, 'appnexus');

​
Cohort Patterns

// Personalize content based on cohorts
permutive.ready(function() {
  permutive.segment(12345, function(isPremiumUser) {
    if (isPremiumUser) {
      showPremiumLayout();
      hideAds();
    }
  });
}, 'realtime');

​
Event-Based Cohort Updates

Cohorts update in real-time as users take actions: 
// User reads an article about sports
permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      categories: ['sports', 'football']
    }
  }
});

// Moments later, check if they entered the sports cohort
permutive.trigger(12345, 'segment', function(inSportsCohort) {
  if (inSportsCohort) {
    console.log('User just qualified for sports cohort!');
  }
});

​
Debugging Cohorts

Enable debug mode to see cohort activity: 
?permutive_debug=true
Console output includes: 
[Permutive] Segments updated: [12345, 67890, ...]
[Permutive] User entered segment: 12345
[Permutive] DFP segments: [12345]

​
Troubleshooting

Problem: No cohorts even after tracking events.Solutions:
  • Use ready('realtime') to wait for data
  • Check that events are being tracked (debug mode)
  • Verify cohorts are configured in dashboard
  • Ensure user hasn’t opted out (consent)
  • Allow time for cohort processing (seconds to minutes)
Problem: Events tracked but user not in cohort.Solutions:
  • Verify cohort rules in dashboard
  • Check event properties match rule conditions
  • Confirm cohort is active (not paused/archived)
  • Check cohort minimum threshold/frequency
Problem: User in cohort but activation array differs.Solutions:
  • Check that cohort is activated for the platform
  • Verify activation configuration in dashboard
  • Use correct type parameter: segments(cb, 'dfp')
Problem: Cohorts not updating after new events.Solutions:
  • Cohorts update in real-time but may take a few seconds
  • Refresh page to trigger re-evaluation
  • Check that new events are actually being tracked
  • Use trigger() for real-time change detection

Real-Time Triggers

React to cohort changes

Custom Cohorts

Build cohorts in dashboard

Contextual Cohorts

Content-based cohorts

Google Ad Manager

GAM targeting setup