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 currentCohorts and activations via currentActivations. 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:
val permutive = (application as MyApplication).permutive
val currentCohorts: List<String> = permutive.currentCohorts

currentCohorts.forEach { cohortId ->
    Log.d("Permutive", "User is in cohort: $cohortId")
}
currentCohorts and currentActivations return snapshot values at the time they’re called. For real-time updates, use TriggersProvider.

​
Use Cases

class PersonalizedHomeActivity : AppCompatActivity() {

    private val permutive by lazy { (application as MyApplication).permutive }

    private fun personalizeContent() {
        val cohorts = permutive.currentCohorts

        when {
            "premium_subscriber" in cohorts -> showPremiumContent()
            "sports_enthusiast" in cohorts -> showSportsRecommendations()
            "tech_reader" in cohorts -> showTechRecommendations()
            else -> showGeneralContent()
        }
    }
}

class ExperimentalFeatureActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val cohorts = permutive.currentCohorts

        // Use cohort membership as feature flag
        val enableNewCheckout = "checkout_experiment_v2" in cohorts

        if (enableNewCheckout) {
            setContentView(R.layout.activity_checkout_v2)
        } else {
            setContentView(R.layout.activity_checkout_v1)
        }
    }
}
Activations are automatically used by our add-on libraries:
// Google Ad Manager (automatic with add-on)
val adRequest = AdManagerAdRequest.Builder()
    .addPermutiveTargeting(permutive)  // Adds activations automatically
    .build()

// AppNexus (automatic with add-on)
adView.addPermutiveTargeting(permutive)  // Adds activations automatically

class AnalyticsHelper(private val permutive: Permutive) {

    fun logUserSegments() {
        val cohorts = permutive.currentCohorts

        // Log to your analytics platform
        Analytics.setUserProperty("permutive_cohorts", cohorts.joinToString(","))
        Analytics.logEvent("cohort_count", mapOf("count" to cohorts.size))
    }

    fun getActivationInfo(): Map<String, Any> {
        val activations = permutive.currentActivations
        return mapOf(
            "gam_cohort_count" to (activations["dfp"]?.size ?: 0),
            "appnexus_cohort_count" to (activations["appnexus_adserver"]?.size ?: 0),
            "has_contextual" to (activations["dfp_contextual"]?.isNotEmpty() ?: false)
        )
    }
}

​
Contextual Cohorts in Detail

Contextual cohorts require SDK version 1.10.0+, feature enabled by your CSM, and page/video tracking with URLs. 
// Track a page with URL
val pageTracker = permutive.trackPage(
    title = "Electric Vehicle Buying Guide",
    url = Uri.parse("https://example.com/articles/ev-buying-guide"),
    eventProperties = EventProperties.from(
        "category" to "automotive",
        "subcategory" to "electric_vehicles"
    )
)

// Contextual cohorts appear in activations
val contextualCohorts = permutive.currentActivations["dfp_contextual"].orEmpty()
// ["automotive_ev", "automotive_buying_guides", "sustainability"]

// Used automatically in ad requests
val adRequest = AdManagerAdRequest.Builder()
    .addPermutiveTargeting(permutive)  // Includes contextual cohorts
    .build()

Contextual Data Guide

Complete contextual cohorts documentation

​
Deprecated APIs

The SDK previously used integer-based segment IDs. These are now deprecated: 
// Old (Deprecated)
val segments: List<Int> = permutive.currentSegments
val reactions: Map<String, List<Int>> = permutive.currentReactions

// New
val cohorts: List<String> = permutive.currentCohorts
val activations: Map<String, List<String>> = permutive.currentActivations
Classification Model cohorts and contextual cohorts use string identifiers. The new APIs support all cohort types uniformly.

​
Troubleshooting

Problem: currentCohorts returns an empty list.Solutions:
  • Wait a few seconds after initialization
  • Track some events and check again
  • Use TriggersProvider for reactive updates
  • Enable debug logging to see sync status
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 1.10.0+
  • Ensure you’re using PageTracker with valid URLs
  • Check debug logs for classification errors

​
Best Practices

  • Use currentCohorts for one-time checks
  • Use TriggersProvider for reactive updates
  • Check activation keys exist before accessing
  • Handle empty lists gracefully
  • Log cohorts for debugging (in development only)

Triggers Provider

Reactive cohort updates

Contextual Data

Content-based segmentation

Google Ad Manager

GAM integration

Xandr Integration

AppNexus integration