Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.permutive.com/llms.txt

Use this file to discover all available pages before exploring further.

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