> ## 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" 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 `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

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

    <CodeGroup>
      ```swift Swift theme={"dark"}
      let currentCohorts: Set<String> = Permutive.shared.cohorts

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

      ```objectivec Objective-C theme={"dark"}
      NSSet<NSString *> *currentCohorts = [Permutive.shared cohorts];

      for (NSString *cohortId in currentCohorts) {
          NSLog(@"User is in cohort: %@", cohortId);
      }
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```swift Swift theme={"dark"}
      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"] ?? []
      ```

      ```objectivec Objective-C theme={"dark"}
      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"] ?: @[];
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```swift Swift theme={"dark"}
      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
      }
      ```

      ```objectivec Objective-C theme={"dark"}
      @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];
                  }
              }];
      }
      ```
    </CodeGroup>

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

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

## Use Cases

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

      ```objectivec Objective-C theme={"dark"}
      - (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];
          }
      }
      ```
    </CodeGroup>
  </Accordion>

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

  <Accordion title="Dynamic Ad Targeting" icon="bullseye">
    Activations are used with ad targeting:

    <CodeGroup>
      ```swift Swift theme={"dark"}
      // Google Ad Manager
      let adRequest = GAMRequest()
      adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
          adTargetable: pageTracker
      )
      bannerView.load(adRequest)
      ```

      ```objectivec Objective-C theme={"dark"}
      // Google Ad Manager
      GAMRequest *adRequest = [GAMRequest request];
      adRequest.customTargeting = [Permutive.shared
          googleCustomTargetingWithAdTargetable:self.pageTracker];
      [self.bannerView loadRequest:adRequest];
      ```
    </CodeGroup>
  </Accordion>

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

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

<CodeGroup>
  ```swift Swift theme={"dark"}
  // 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
  )
  ```

  ```objectivec Objective-C theme={"dark"}
  // 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"] ?: @[];
  ```
</CodeGroup>

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

## tvOS Considerations

<Info>
  **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.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </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 2.0.0+
    * Ensure you're using PageTracker with valid URLs
    * Verify the URL is publicly accessible
    * Check debug logs for classification errors
  </Accordion>
</AccordionGroup>

## Best Practices

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

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

## Related Documentation

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

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

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

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