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: 
User's Cohorts: ["sports_enthusiast", "premium_subscriber", "mobile_user", "frequent_visitor"]

Activations:
  - dfp: ["sports_enthusiast", "premium_subscriber"]  // Only 2 activated for GAM
  - freewheel: ["sports_enthusiast"]                   // Only 1 activated for Freewheel

​
Accessing Cohorts and Activations

Get all cohorts the user currently belongs to:
let currentCohorts: Set<String> = Permutive.shared.cohorts

for cohortId in currentCohorts {
    print("User is in cohort: \(cohortId)")
}
cohorts and activations return snapshot values at the time they’re called. For real-time updates, use TriggerProvider.

​
Use Cases

class PersonalizedHomeViewController: UIViewController {

    func personalizeContent() {
        let cohorts = Permutive.shared.cohorts

        if cohorts.contains("premium_subscriber") {
            showPremiumContent()
        } else if cohorts.contains("sports_enthusiast") {
            showSportsRecommendations()
        } else if cohorts.contains("tech_reader") {
            showTechRecommendations()
        } else {
            showGeneralContent()
        }
    }
}

class ExperimentalFeatureViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        let cohorts = Permutive.shared.cohorts

        // Use cohort membership as feature flag
        let enableNewCheckout = cohorts.contains("checkout_experiment_v2")

        if enableNewCheckout {
            setupNewCheckoutUI()
        } else {
            setupClassicCheckoutUI()
        }
    }
}
Activations are used with ad targeting:
// Google Ad Manager
let adRequest = GAMRequest()
adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
    adTargetable: pageTracker
)
bannerView.load(adRequest)

class AnalyticsHelper {
    func logUserSegments() {
        let cohorts = Permutive.shared.cohorts

        // Log to your analytics platform
        Analytics.setUserProperty(
            "permutive_cohorts",
            value: cohorts.joined(separator: ",")
        )
        Analytics.logEvent(
            "cohort_count",
            parameters: ["count": cohorts.count]
        )
    }

    func getActivationInfo() -> [String: Any] {
        let activations = Permutive.shared.activations
        return [
            "gam_cohort_count": activations["dfp"]?.count ?? 0,
            "appnexus_cohort_count": activations["appnexus_adserver"]?.count ?? 0,
            "has_contextual": (activations["dfp_contextual"]?.isEmpty == false)
        ]
    }
}

​
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. 
// Track a page with URL
let properties = try? EventProperties([
    "category": "automotive",
    "subcategory": "electric_vehicles"
])

let context = Context(
    title: "Electric Vehicle Buying Guide",
    url: URL(string: "https://example.com/articles/ev-buying-guide"),
    referrer: nil
)

let pageTracker = try? Permutive.shared.createPageTracker(
    properties: properties,
    context: context
)
try? pageTracker?.resume()

// Contextual cohorts appear in activations
let contextualCohorts = Permutive.shared.activations["dfp_contextual"] ?? []
// Example: ["automotive_ev", "automotive_buying_guides", "sustainability"]

// Used automatically in ad requests
let adRequest = GAMRequest()
adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
    adTargetable: pageTracker
)

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