Skip to main content
Understanding cohorts and activations is fundamental to using the Permutive SDK effectively.

Cohorts

Activations

Contextual

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"

What are 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

Available 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
In the SDK, access cohorts via cohorts and activations via activations. Example:

Accessing Cohorts and Activations

Get all cohorts the user currently belongs to:
cohorts and activations return snapshot values at the time they’re called. For real-time updates, use TriggerProvider.

Async API

Requires SDK v3.0.0+. These methods use Swift concurrency (async/await) and are available in Swift only.
The async variants - cohorts(), activations(), and googleCustomTargeting(adTargetable:) - wait for cohorts and activations to settle (for any events still being processed) before returning the current values. If they don’t settle within a short timeout (defaults to 500ms), the methods fall back to the currently cached values. This matters most for time-sensitive ad requests: after tracking the page a user just opened, you want the ad request’s targeting to reflect that page rather than the previous one. Awaiting googleCustomTargeting(adTargetable:) gives the new cohorts a brief window to settle, then builds targeting from the freshest values available. Get cohorts, awaiting any pending events:
Get activations, awaiting any pending events:
Build an ad request whose targeting reflects the page the user just opened:
Reach for the async methods when timing matters (right after tracking). For a quick read where pending cohorts are possible, the synchronous cohorts / activations properties avoid the await.

Use Cases

Activations are used with ad targeting:

Contextual Cohorts

Contextual cohorts are generated in real-time based on content being viewed. They require SDK version 2.0.0+ and feature enablement by your CSM.

Contextual Data Guide

Complete contextual cohorts documentation

tvOS Considerations

tvOS Note: Cohorts and activations work identically on tvOS. The same APIs are available, and cohort data syncs across all Apple platforms when identity is set.

Troubleshooting

Problem: cohorts returns an empty set.Solutions:
  • Wait a few seconds after initialization
  • Track some events to generate data
  • Use TriggerProvider for reactive updates
  • Enable debug logging to see sync status
  • Verify cohorts are configured in your dashboard
Problem: User is in a cohort but it doesn’t appear in activations.Cause: Not all cohorts are activated for all platforms. This is configured in your Permutive dashboard.Solution: Check your dashboard configuration or contact your Customer Success Manager.
Problem: dfp_contextual activations are empty.Solutions:
  • Verify feature is enabled with your CSM
  • Update to SDK 2.0.0+
  • Ensure you’re using PageTracker with valid URLs
  • Verify the URL is publicly accessible
  • Check debug logs for classification errors

Best Practices

  • Use cohorts for one-time checks
  • Use TriggerProvider for reactive updates
  • Check activation keys exist before accessing
  • Handle empty sets gracefully
  • Log cohorts for debugging (in development only)
  • Cache cohort checks that are expensive to re-evaluate

Triggers Provider

Reactive cohort updates

Contextual Data

Content-based segmentation

Google Ad Manager

GAM integration

Xandr Integration

AppNexus integration