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

# Cohorts and Activations

> Understanding user segmentation and platform-specific targeting

export const CohortsVsActivationsTable = () => <table>
    <thead>
      <tr>
        <th>Aspect</th>
        <th>Cohorts</th>
        <th>Activations</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><strong>Definition</strong></td>
        <td>All segments a user belongs to</td>
        <td>Cohorts configured for specific platforms</td>
      </tr>
      <tr>
        <td><strong>Scope</strong></td>
        <td>Entire Permutive system</td>
        <td>Platform-specific</td>
      </tr>
      <tr>
        <td><strong>Purpose</strong></td>
        <td>User segmentation</td>
        <td>Ad targeting</td>
      </tr>
      <tr>
        <td><strong>Configuration</strong></td>
        <td>Automatic based on events</td>
        <td>Configured in dashboard</td>
      </tr>
    </tbody>
  </table>;

export const ActivationTypesTable = () => <table>
    <thead>
      <tr>
        <th>Activation Type</th>
        <th>Platform</th>
        <th>Use Case</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code>dfp</code></td>
        <td>Google Ad Manager</td>
        <td>Standard behavioral cohort activations</td>
      </tr>
      <tr>
        <td><code>dfp_contextual</code></td>
        <td>Google Ad Manager</td>
        <td>Real-time contextual cohorts</td>
      </tr>
      <tr>
        <td><code>appnexus_adserver</code></td>
        <td>Xandr/AppNexus</td>
        <td>Standard behavioral cohort activations</td>
      </tr>
      <tr>
        <td><code>appnexus_adserver_contextual</code></td>
        <td>Xandr/AppNexus</td>
        <td>Real-time contextual cohorts</td>
      </tr>
      <tr>
        <td><code>freewheel</code></td>
        <td>Freewheel</td>
        <td>CTV/video ad targeting</td>
      </tr>
    </tbody>
  </table>;

export const ActivationDefinition = () => <>
    <p><strong>Activations</strong> 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.</p>
    <AccordionGroup>
      <Accordion title="Why use Activations?" icon="circle-question">
        <ul>
          <li><strong>Platform-specific targeting</strong> - Different ad platforms may need different cohorts</li>
          <li><strong>Data governance</strong> - Control which platforms receive which user segments</li>
          <li><strong>Performance optimization</strong> - Only send relevant cohorts to each platform</li>
          <li><strong>Compliance</strong> - Manage consent and privacy requirements per platform</li>
        </ul>
      </Accordion>
    </AccordionGroup>
  </>;

export const CohortTypes = () => <Tabs>
    <Tab title="Behavioral">
      <p>Based on user actions and event patterns tracked through the SDK.</p>
      <p><strong>Example:</strong> A user who reads 5+ sports articles becomes part of the "sports_enthusiast" cohort.</p>
      <pre><code>{`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"`}</code></pre>
    </Tab>
    <Tab title="Classification Model">
      <p>Generated using machine learning models that predict user characteristics.</p>
      <p><strong>Example:</strong> ML model predicts user is likely to purchase premium subscription based on browsing patterns.</p>
    </Tab>
    <Tab title="Contextual">
      <p>Based on real-time content analysis of the current page or video being viewed.</p>
      <p><strong>Example:</strong> User viewing a page about electric vehicles gets contextual cohort "automotive_electric_vehicles" for that session.</p>
      <p><strong>Key characteristics:</strong></p>
      <ul>
        <li><strong>Real-time</strong> - Generated immediately when content is viewed</li>
        <li><strong>Transient</strong> - Only active while viewing the content</li>
        <li><strong>Privacy-friendly</strong> - No long-term user profiling required</li>
      </ul>
    </Tab>
  </Tabs>;

export const CohortDefinition = () => <>
    <p>A <strong>cohort</strong> is a privacy-safe representation of an audience.</p>
    <p>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.</p>
    <p>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.</p>
    <p>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.</p>
  </>;

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

<CardGroup cols={3}>
  <Card title="Cohorts" href="#what-are-cohorts" icon="users" />

  <Card title="Activations" href="#what-are-activations" icon="bullseye" />

  <Card title="Contextual" href="#contextual-cohorts-in-detail" icon="file-lines" />
</CardGroup>

## What are Cohorts?

<CohortDefinition />

### Cohort Types

<CohortTypes />

## What are Activations?

<ActivationDefinition />

### Available Activation Types

<ActivationTypesTable />

## Cohorts vs. Activations

<CohortsVsActivationsTable />

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

<Tabs>
  <Tab title="Get Cohorts">
    Get all cohorts the user currently belongs to:

    <CodeGroup>
      ```kotlin Kotlin theme={"dark"}
      val permutive = (application as MyApplication).permutive
      val currentCohorts: List<String> = permutive.currentCohorts

      currentCohorts.forEach { cohortId ->
          Log.d("Permutive", "User is in cohort: $cohortId")
      }
      ```

      ```java Java theme={"dark"}
      Permutive permutive = ((MyApplication) getApplication()).getPermutive();
      List<String> currentCohorts = permutive.getCurrentCohorts();

      for (String cohortId : currentCohorts) {
          Log.d("Permutive", "User is in cohort: " + cohortId);
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Get Activations">
    Get cohorts activated for specific platforms:

    <CodeGroup>
      ```kotlin Kotlin theme={"dark"}
      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()
      ```

      ```java Java theme={"dark"}
      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());
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Reactive Updates">
    For real-time cohort changes, use `TriggersProvider`:

    ```kotlin theme={"dark"}
    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()
    }
    ```

    <Card title="TriggersProvider Guide" icon="bell" href="/sdks/mobile/android/features/triggers-provider">
      Complete documentation for reactive updates
    </Card>
  </Tab>
</Tabs>

<Tip>
  `currentCohorts` and `currentActivations` return **snapshot values** at the time they're called. For real-time updates, use TriggersProvider.
</Tip>

## Use Cases

<AccordionGroup>
  <Accordion title="Personalization" icon="wand-magic-sparkles">
    ```kotlin theme={"dark"}
    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()
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Feature Flags / A/B Testing" icon="flask">
    ```kotlin theme={"dark"}
    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)
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Ad Targeting" icon="bullseye">
    Activations are automatically used by our add-on libraries:

    ```kotlin theme={"dark"}
    // 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
    ```
  </Accordion>

  <Accordion title="Analytics and Logging" icon="chart-line">
    ```kotlin theme={"dark"}
    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)
            )
        }
    }
    ```
  </Accordion>
</AccordionGroup>

## Contextual Cohorts in Detail

Contextual cohorts require SDK version 1.10.0+, feature enabled by your CSM, and page/video tracking with URLs.

```kotlin theme={"dark"}
// 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()
```

<Card title="Contextual Data Guide" icon="bullseye" href="/sdks/mobile/android/core-concepts/contextual-data">
  Complete contextual cohorts documentation
</Card>

## Deprecated APIs

The SDK previously used integer-based segment IDs. These are now deprecated:

```kotlin theme={"dark"}
// 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
```

<Note>
  Classification Model cohorts and contextual cohorts use string identifiers. The new APIs support all cohort types uniformly.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Best Practices

<Tabs>
  <Tab title="Do">
    * 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)
  </Tab>

  <Tab title="Don't">
    * 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)
  </Tab>
</Tabs>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Triggers Provider" icon="bell" href="/sdks/mobile/android/features/triggers-provider">
    Reactive cohort updates
  </Card>

  <Card title="Contextual Data" icon="bullseye" href="/sdks/mobile/android/core-concepts/contextual-data">
    Content-based segmentation
  </Card>

  <Card title="Google Ad Manager" icon="google" href="/sdks/mobile/android/integrations/google-ad-manager">
    GAM integration
  </Card>

  <Card title="Xandr Integration" icon="rectangle-ad" href="/sdks/mobile/android/integrations/appnexus-xandr">
    AppNexus integration
  </Card>
</CardGroup>