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

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

Permutive permutive = ((MyApplication) getApplication()).getPermutive();
List<String> currentCohorts = permutive.getCurrentCohorts();

for (String cohortId : currentCohorts) {
    Log.d("Permutive", "User is in cohort: " + cohortId);
}

Get cohorts activated for specific platforms:

val currentActivations: Map<String, List<String>> = permutive.currentActivations

// Get Google Ad Manager activations
val gamActivations = currentActivations["dfp"].orEmpty()

// Get AppNexus activations
val appNexusActivations = currentActivations["appnexus_adserver"].orEmpty()

// Get contextual activations
val gamContextual = currentActivations["dfp_contextual"].orEmpty()

Map<String, List<String>> currentActivations = permutive.getCurrentActivations();

// Get Google Ad Manager activations
List<String> gamActivations = currentActivations.getOrDefault("dfp", Collections.emptyList());

// Get AppNexus activations
List<String> appNexusActivations =
    currentActivations.getOrDefault("appnexus_adserver", Collections.emptyList());

For real-time cohort changes, use TriggersProvider:

val triggersProvider = permutive.triggersProvider()

// Get notified when user enters/exits a cohort
val trigger = triggersProvider.triggerAction("premium_subscriber") { isInCohort ->
    if (isInCohort) {
        showPremiumFeatures()
    } else {
        hidePremiumFeatures()
    }
}

// Don't forget to close when done
override fun onDestroy() {
    super.onDestroy()
    trigger.close()
}

TriggersProvider Guide

Complete documentation for reactive updates

currentCohorts and currentActivations return snapshot values at the time they’re called. For real-time updates, use TriggersProvider.

Use Cases

Personalization

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

Feature Flags / A/B Testing

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

Dynamic Ad Targeting

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

Analytics and Logging

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

Empty cohorts list

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

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 1.10.0+
Ensure you’re using PageTracker with valid URLs
Check debug logs for classification errors

Best Practices

Do
Don't

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)

Poll currentCohorts repeatedly (use TriggersProvider 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

TriggersProvider Guide

Use Cases

Contextual Cohorts in Detail

Contextual Data Guide

Deprecated APIs

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

TriggersProvider Guide

​Use Cases

​Contextual Cohorts in Detail

Contextual Data Guide

​Deprecated APIs

​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

Use Cases

Contextual Cohorts in Detail

Deprecated APIs

Troubleshooting

Best Practices

Related Documentation