Cohorts and Activations

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

Cohorts

Activations

Contextual

What are Cohorts?

Cohort Types

What are Activations?

Available Activation Types

Cohorts vs. Activations

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 Cohorts
Get Activations
Reactive Updates

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)")
}

NSSet<NSString *> *currentCohorts = [Permutive.shared cohorts];

for (NSString *cohortId in currentCohorts) {
    NSLog(@"User is in cohort: %@", cohortId);
}

Get cohorts activated for specific platforms:

let activations: [String: [String]] = Permutive.shared.activations

// Get Google Ad Manager activations
let gamActivations = activations["dfp"] ?? []

// Get AppNexus activations
let appNexusActivations = activations["appnexus_adserver"] ?? []

// Get Freewheel activations
let freewheelActivations = activations["freewheel"] ?? []

// Get contextual activations
let gamContextual = activations["dfp_contextual"] ?? []

NSDictionary<NSString *, NSArray<NSString *> *> *activations =
    [Permutive.shared activations];

// Get Google Ad Manager activations
NSArray<NSString *> *gamActivations = activations[@"dfp"] ?: @[];

// Get AppNexus activations
NSArray<NSString *> *appNexusActivations = activations[@"appnexus_adserver"] ?: @[];

For real-time cohort changes, use TriggerProvider:

var trigger: TriggerAction?

func watchCohort() {
    trigger = Permutive.shared.triggerProvider?.action(
        boolFor: ["premium_subscriber"],
        action: { query, isInCohort in
            if isInCohort {
                self.showPremiumFeatures()
            } else {
                self.hidePremiumFeatures()
            }
        }
    )
}

// Release when done
deinit {
    trigger = nil
}

@property (nonatomic, strong) PermutiveTriggerAction *trigger;

- (void)watchCohort {
    NSSet *cohorts = [NSSet setWithObject:@"premium_subscriber"];
    self.trigger = [Permutive.shared.triggerProvider
        actionWithBoolFor:cohorts
        action:^(NSString *cohort, BOOL isInCohort) {
            if (isInCohort) {
                [self showPremiumFeatures];
            } else {
                [self hidePremiumFeatures];
            }
        }];
}

Triggers Provider Guide

Complete documentation for reactive updates

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:

let currentCohorts: Set<String> = await Permutive.shared.cohorts()

for cohortId in currentCohorts {
    print("User is in cohort: \(cohortId)")
}

Get activations, awaiting any pending events:

let activations: [String: [String]] = await Permutive.shared.activations()
let gamActivations = activations["dfp"] ?? []

Build an ad request whose targeting reflects the page the user just opened:

let adRequest = GAMRequest()
adRequest.customTargeting = await Permutive.shared.googleCustomTargeting(
    adTargetable: pageTracker
)
bannerView.load(adRequest)

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

Personalization

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()
        }
    }
}

- (void)personalizeContent {
    NSSet<NSString *> *cohorts = [Permutive.shared cohorts];

    if ([cohorts containsObject:@"premium_subscriber"]) {
        [self showPremiumContent];
    } else if ([cohorts containsObject:@"sports_enthusiast"]) {
        [self showSportsRecommendations];
    } else if ([cohorts containsObject:@"tech_reader"]) {
        [self showTechRecommendations];
    } else {
        [self showGeneralContent];
    }
}

Feature Flags / A/B Testing

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()
        }
    }
}

Dynamic Ad Targeting

Activations are used with ad targeting:

// Google Ad Manager
let adRequest = GAMRequest()
adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
    adTargetable: pageTracker
)
bannerView.load(adRequest)

// Google Ad Manager
GAMRequest *adRequest = [GAMRequest request];
adRequest.customTargeting = [Permutive.shared
    googleCustomTargetingWithAdTargetable:self.pageTracker];
[self.bannerView loadRequest:adRequest];

Analytics and Logging

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
)

// Track a page with URL
NSError *error = nil;
PermutiveEventProperties *properties = [[PermutiveEventProperties alloc]
    init:@{@"category": @"automotive", @"subcategory": @"electric_vehicles"}
    error:&error];

PermutiveContext *context = [[PermutiveContext alloc]
    initWithTitle:@"Electric Vehicle Buying Guide"
    url:[NSURL URLWithString:@"https://example.com/articles/ev-buying-guide"]
    referrer:nil];

NSObject<PermutivePageTrackerProtocol> *pageTracker =
    [Permutive.shared createPageTrackerWithProperties:properties
                                              context:context
                                                error:&error];
[pageTracker resumeAndReturnError:nil];

// Contextual cohorts appear in activations
NSArray *contextualCohorts = [Permutive.shared activations][@"dfp_contextual"] ?: @[];

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

Empty cohorts

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

Activations different from cohorts

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.

Contextual cohorts not appearing

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

Do
Don't

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

Poll cohorts repeatedly (use TriggerProvider instead)
Assume cohorts will be available immediately after initialization
Hard-code cohort IDs without checking dashboard
Share PII in cohort names or IDs
Cache cohorts for long periods (they can change)

Triggers Provider

Reactive cohort updates

Contextual Data

Content-based segmentation

Google Ad Manager

GAM integration

Xandr Integration

AppNexus integration

Get Started

Products

Deployment

Governance

Cohorts and Activations

Cohorts

Activations

Contextual

What are Cohorts?

Cohort Types

What are Activations?

Available Activation Types

Cohorts vs. Activations

Accessing Cohorts and Activations

Triggers Provider Guide

Async API

Use Cases

Contextual Cohorts

Contextual Data Guide

tvOS Considerations

Troubleshooting

Best Practices

Triggers Provider

Contextual Data

Google Ad Manager

Xandr Integration

Cohorts

Activations

Contextual

​What are Cohorts?

​Cohort Types

​What are Activations?

​Available Activation Types

​Cohorts vs. Activations

​Accessing Cohorts and Activations

Triggers Provider Guide

​Async API

​Use Cases

​Contextual Cohorts

Contextual Data Guide

​tvOS Considerations

​Troubleshooting

​Best Practices

​Related Documentation

Triggers Provider

Contextual Data

Google Ad Manager

Xandr Integration

What are Cohorts?

Cohort Types

What are Activations?

Available Activation Types

Cohorts vs. Activations

Accessing Cohorts and Activations

Async API

Use Cases

Contextual Cohorts

tvOS Considerations

Troubleshooting

Best Practices

Related Documentation