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

# FreeWheel

> Integrate with FreeWheel for targeting and campaign optimization

export const NoBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#F7D0E2',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      No
    </span>;
};

export const YesBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#C7E8F9',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      Yes
    </span>;
};

export const BadgeRowCenter = ({label, children}) => {
  return <div style={{
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'center',
    marginBottom: '0.5rem'
  }}>
      <span style={{
    fontSize: '0.625rem',
    color: '#6b7280',
    textTransform: 'uppercase',
    fontWeight: '500',
    letterSpacing: '0.05em'
  }}>
        {label}
      </span>
      {children}
    </div>;
};

export const BadgeRow = ({label, children}) => {
  return <div style={{
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'flex-start',
    marginBottom: '0.5rem'
  }}>
      <span style={{
    fontSize: '0.625rem',
    color: '#6b7280',
    textTransform: 'uppercase',
    fontWeight: '500',
    letterSpacing: '0.05em'
  }}>
        {label}
      </span>
      {children}
    </div>;
};

export const BadgeContainer = ({children}) => {
  return <div style={{
    display: 'flex',
    gap: '0.25rem',
    flexWrap: 'wrap',
    justifyContent: 'flex-end',
    minWidth: '0',
    flex: '1'
  }}>
      {children}
    </div>;
};

export const ProductRequiredBadge = ({product}) => {
  const getBadgeStyle = product => {
    switch (product) {
      case 'Core Platform':
        return {
          background: '#CB88FC',
          color: '#1A1A1A'
        };
        --purple;
      case 'Routing':
        return {
          background: '#CB88FC',
          color: '#1A1A1A'
        };
        --purple;
      case 'Contextual':
        return {
          background: '#CB88FC',
          color: '#1A1A1A'
        };
        --purple;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(product);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500'
  }}>
      {product}
    </span>;
};

export const SdkRequiredBadge = ({required}) => {
  const getBadgeStyle = required => {
    switch (required) {
      case 'Yes':
        return {
          background: '#C7E8F9',
          color: '#1A1A1A'
        };
        --blue;
      case 'No':
        return {
          background: '#F7D0E2',
          color: '#1A1A1A'
        };
        --pink;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(required);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500'
  }}>
      {required}
    </span>;
};

export const CapabilityBadge = ({capability}) => {
  const getBadgeStyle = capability => {
    switch (capability) {
      case 'Event Collection':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Cohort Activation':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Campaign Optimization':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Identity Signal':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Contextual Signal':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Connectivity':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Routing':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Data Collaboration':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(capability);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
      {capability}
    </span>;
};

export const EnvironmentBadge = ({environment}) => {
  const getBadgeStyle = environment => {
    switch (environment) {
      case 'Web':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'iOS':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'Android':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'CTV':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'API Direct':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(environment);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
      {environment}
    </span>;
};

export const DirectionBadge = ({direction}) => {
  const getBadgeStyle = direction => {
    switch (direction) {
      case 'Bidirectional':
        return {
          background: '#FA8784',
          color: '#1A1A1A'
        };
        --tomato;
      case 'Destination':
        return {
          background: '#FA8784',
          color: '#1A1A1A'
        };
        --tomato;
      case 'Source':
        return {
          background: '#FA8784',
          color: '#1A1A1A'
        };
        --tomato;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(direction);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500'
  }}>
      {direction}
    </span>;
};

<Card title="">
  <div style={{ display: 'flex', alignItems: 'center', marginBottom: '1rem' }}>
    <div style={{ width: '32px', height: '32px', marginRight: '0.75rem', display: 'flex', alignItems: 'center', justifyContent: 'center', flexShrink: 0 }}>
      <img src="https://mintcdn.com/permutive/tY6HQAw8J0a8II15/images/integrations/logos/freewheel-icon.png?fit=max&auto=format&n=tY6HQAw8J0a8II15&q=85&s=154a46d899cd3da68fc8ac012f174a15" alt="FreeWheel" style={{ maxWidth: '32px', maxHeight: '32px', display: 'block' }} width="256" height="256" data-path="images/integrations/logos/freewheel-icon.png" />
    </div>

    <h3 style={{ margin: 0, fontSize: '1.125rem', fontWeight: '600' }}>FreeWheel</h3>
  </div>

  <div style={{ marginBottom: '1rem' }}>
    <BadgeRowCenter label="Direction">
      <DirectionBadge direction="Destination" />
    </BadgeRowCenter>

    <BadgeRowCenter label="Environment">
      <BadgeContainer>
        <EnvironmentBadge environment="Web" />

        <EnvironmentBadge environment="iOS" />

        <EnvironmentBadge environment="Android" />

        <EnvironmentBadge environment="CTV" />
      </BadgeContainer>
    </BadgeRowCenter>

    <BadgeRowCenter label="Capability">
      <BadgeContainer>
        <CapabilityBadge capability="Cohort Activation" />
      </BadgeContainer>
    </BadgeRowCenter>

    <BadgeRowCenter label="SDK Required">
      <SdkRequiredBadge required="Yes" />
    </BadgeRowCenter>

    <BadgeRowCenter label="Product(s) Required">
      <ProductRequiredBadge product="Core Platform" />
    </BadgeRowCenter>
  </div>

  <p style={{ margin: 0, fontSize: '0.875rem', color: '#6b7280', lineHeight: '1.5' }}>
    FreeWheel offers a premium video ad server and SSP tailored to broadcasters and publishers for advanced monetization.
  </p>
</Card>

<CardGroup cols={2}>
  <Card title="Setup" href="#setup" icon="gear" />

  <Card title="Troubleshooting" href="#troubleshooting" icon="wrench" />
</CardGroup>

## Overview

FreeWheel is a premium video ad server used by media companies, broadcasters, and publishers with significant video content and ad inventory. Our integration with FreeWheel enables activation of Permutive cohorts for campaign targeting within the FreeWheel ad server. This integration supports two distinct activation methods:

**Key-Value Activation:** Real-time cohort activation via FreeWheel Federated Segments (Web, iOS, Android, CTV, API Direct). Cohort IDs are stored in local storage (Web), retrieved via SDK APIs (iOS/Android), or returned from the CCS API (API Direct).

**Identity Based Activation:** Server-to-server cohort activation where Permutive uploads audience data enriched with cohort memberships to FreeWheel, keyed by identity types such as AAID, IDFA, and IP Address. Cohorts appear as Audiences in FreeWheel.

Use cases include:

* Activate Permutive cohorts in FreeWheel for real-time audience targeting on video inventory across all environments
* Target premium video campaigns using first-party data segments from Permutive
* Enable audience extension by activating cohorts on non-owned properties (Identity Based)
* Share audience data across business units using identity-based activation
* Enable broadcasters and publishers to monetize video content more effectively with data-driven targeting

## Choosing an Activation Method

FreeWheel supports two activation methods. Choose the method that best fits your use case:

| Aspect                | Key-Value Activation                                            | Identity Based Activation                            |
| --------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| **Mechanism**         | Client-side, cohort IDs appended to ad requests                 | Server-to-server transfer                            |
| **Environments**      | Web, iOS, Android, CTV, API Direct                              | Web, iOS, Android, CTV, API Direct                   |
| **Sync Timing**       | Real-time                                                       | Daily                                                |
| **FreeWheel Feature** | Federated Segments                                              | Audiences                                            |
| **Use Cases**         | Real-time targeting on owned properties across all environments | Audience extension, cross business unit data sharing |

## Environment Compatibility

The table below shows which activation method is available for each environment:

| Environment    | Key-Value Activation | Identity Based Activation |
| -------------- | -------------------- | ------------------------- |
| **Web**        | <YesBadge />         | <YesBadge />              |
| **iOS**        | <YesBadge />         | <YesBadge />              |
| **Android**    | <YesBadge />         | <YesBadge />              |
| **CTV**        | <YesBadge />         | <YesBadge />              |
| **API Direct** | <YesBadge />         | <YesBadge />              |

## Prerequisites

**For Key-Value Activation:**

* **FreeWheel Account** - You must have an active FreeWheel ad server account
* **FreeWheel Client ID** - Your unique FreeWheel Client ID
* **Federated Segments Enabled** - Your FreeWheel account manager must allow Permutive to create Federated Segments in your FreeWheel account
* **Permutive SDK** - The Permutive SDK must be deployed on your web properties where FreeWheel ad requests are made

**For Identity Based Activation:**

* **FreeWheel Account** - You must have an active FreeWheel ad server account
* **FreeWheel Client ID** - Your unique FreeWheel Client ID
* **Permutive Identity Collection** - Identity collection must be configured in Permutive for the identity types you want to send (AAID, IDFA, or IP Address)

## Setup

### Key-Value Activation

<Tabs>
  <Tab title="Primary Setup Steps">
    <Steps>
      <Step title="Contact FreeWheel Account Manager">
        Contact your FreeWheel account manager and ask them to allow Permutive to create Federated Segments in your FreeWheel account. This is required for the integration to work.
      </Step>

      <Step title="Provide Client ID to Permutive">
        Contact your Permutive Customer Success Manager to request the FreeWheel integration. You will need to provide your FreeWheel Client ID.

        Your Permutive Customer Success Manager will enable the FreeWheel integration in your Permutive workspace using this Client ID.
      </Step>

      <Step title="Verify Setup">
        In the Permutive Dashboard, navigate to one of your cohorts. Check that the FreeWheel activation sync is visible. Toggle it to *On* and save the cohort.

        In your FreeWheel dashboard, verify that a new Federated Segment has been created with a name matching your cohort ID. This confirms your integration setup is successful.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Web">
    The FreeWheel integration uses a client-side key-value approach with FreeWheel Federated Segments. When cohorts are activated to FreeWheel in the Permutive Dashboard, Permutive creates a Federated Segment in FreeWheel, and the cohort IDs are stored in the browser's local storage under a FreeWheel-specific key.

    **You must implement code to retrieve these cohort IDs from local storage and append them to your FreeWheel ad requests.** Permutive provides the cohort data, but your implementation is responsible for passing it to FreeWheel.

    #### Accessing FreeWheel Cohorts for Targeting

    Cohort IDs are stored in the local storage variable `_pfws` (this is the default key for FreeWheel activations). This variable is updated as soon as Permutive has segmented the user on the page.

    Below is an example of how to retrieve Permutive cohort IDs in a variable called `cohorts`, which you can then append to your FreeWheel ad requests:

    ```javascript theme={"dark"}
    var cohorts;

    try {
      cohorts = JSON.parse(window.localStorage._pfws || '[]').slice(0, 250).toString();
    } catch (e) {
      cohorts = '';
    }

    // Use the cohorts variable to append to your FreeWheel ad request
    // Example: append as key-value pairs in your ad request configuration
    ```

    #### Implementation Notes

    * Ensure the Permutive SDK loads before you attempt to retrieve cohort IDs from local storage.
    * The cohort IDs are updated in real-time as users enter or exit cohorts.
    * You can append up to 250 cohort IDs per ad request (the `.slice(0, 250)` in the example limits this).
    * Coordinate with your development team to integrate this code into your FreeWheel ad request flow.

    For technical assistance with implementation, contact Permutive Support.
  </Tab>

  <Tab title="iOS">
    Retrieve Permutive cohort IDs for FreeWheel using the `activations` property:

    ```swift theme={"dark"}
    // Import Permutive SDK
    import Permutive

    // Access FreeWheel Cohort IDs directly
    let freeWheelCohorts: [String] = activations['freewheel']

    // Construct your FreeWheel ad request
    // Append Permutive cohorts as key-values
    if !freeWheelCohorts.isEmpty {
        let cohortsString = freeWheelCohorts.joined(separator: ",")
        // Append cohortsString to your FreeWheel ad request
    }
    ```

    **Important Notes:**

    * The `activations` property provides direct access to cohort IDs configured for FreeWheel activation
    * Use the key `freewheel` to retrieve FreeWheel-specific cohorts
    * Coordinate with your development team to integrate this code into your FreeWheel ad request flow
  </Tab>

  <Tab title="Android">
    Retrieve Permutive cohort IDs for FreeWheel using the `TriggersProvider` API. The callback is invoked whenever cohort membership changes:

    ```kotlin theme={"dark"}
    val triggerAction: TriggerAction = triggersProvider.cohortActivations(
        activationType = "freewheel",
        callback = object : Method<List<String>> {
            override fun invoke(cohorts: List<String>) {
                if (cohorts.isNotEmpty()) {
                    // Cohorts available for FreeWheel activation
                    // Pass these to your FreeWheel ad requests as key-values
                    println("FreeWheel cohorts: $cohorts")
                } else {
                    println("No active cohorts with a FreeWheel activation configured.")
                }
            }
        }
    )
    ```

    Once you have the cohort IDs, append them to your FreeWheel ad request.

    **Important Notes:**

    * The `TriggersProvider` API allows you to listen for cohort membership changes
    * Use the activation type `freewheel` to retrieve FreeWheel-specific cohorts
    * See the [Android SDK documentation](https://sdk-docs.permutive.com/core/com.permutive.android/-triggers-provider/query-reactions.html) for more details
  </Tab>

  <Tab title="API Direct">
    In environments where it is not possible to deploy a Permutive SDK (e.g. some CTV environments), you can use Permutive's CCS (Custom Cohort Segmentation) API for event tracking and segmentation instead.

    Access to this API requires customer-specific authorization. You will need a dedicated API key from Permutive.

    ### How it Works

    The CCS API can be used to:

    1. Track events for a specific user (optional)
    2. Retrieve cohort IDs for activation

    <Note>
      The `events` array in the request is optional. If you only need to retrieve cohort memberships without tracking a new event, you can pass an empty array.
    </Note>

    **Example Request:**

    ```bash theme={"dark"}
    curl --request POST \
         --url 'https://api.permutive.app/ccs/v1/segmentation?activations=true&synchronous-validation=false&k=PERMUTIVE_API_KEY' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
      "alias": {
        "tag": "example",
        "id": "12345"
      },
      "events": []
    }
    '
    ```

    The API accepts a user identity passed in the `alias` object. Permutive then either links this identity to an existing Permutive user ID or creates a new Permutive user ID if the identity hasn't been seen before.

    **Example Response:**

    ```json theme={"dark"}
    {
      "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
      "cohorts": ["12345", "23456", "34567"],
      "activations": {
        "freewheel": ["12345", "23456"]
      }
    }
    ```

    The API response includes cohort IDs for FreeWheel activation under the `freewheel` key within the `activations` object. These can then be passed to FreeWheel as key-values for activation.

    **Important Notes:**

    * Replace `PERMUTIVE_API_KEY` with your actual Permutive API key
    * The `activations=true` query parameter is required to receive activation data in the response
  </Tab>
</Tabs>

### Identity Based Activation

<Tabs>
  <Tab title="Primary Setup Steps">
    <Steps>
      <Step title="Contact Permutive CSM">
        Contact your Permutive Customer Success Manager to enable Identity Based Activation for FreeWheel. This is a server-to-server integration that must be configured by Permutive.
      </Step>

      <Step title="Configure in Permutive Dashboard">
        Once enabled, navigate to Settings → Integrations in the Permutive Dashboard. Find "FreeWheel (ID-based)" in the list of available integrations and click to configure it.
      </Step>

      <Step title="Enter FreeWheel Client ID">
        Provide your FreeWheel Client ID in the configuration form. This is the same Client ID used for key-value activation if you have that enabled.
      </Step>

      <Step title="Select Identity Types">
        Choose which identifier types you want to send to FreeWheel. Available options include:

        * **AAID** - Android Advertising ID (for Android app users)
        * **IDFA** - Identifier for Advertisers (for iOS app users)
        * **IP Address** - IP addresses (for CTV and other environments)

        Select the identity types that match your use case and the environments where you need activation.
      </Step>

      <Step title="Save Configuration">
        Save your configuration. Permutive will begin syncing cohort data to FreeWheel on a daily basis for users with the selected identity types.
      </Step>

      <Step title="Activate Cohorts">
        Navigate to your cohorts in the Permutive Dashboard and enable the "FreeWheel (ID-based)" activation toggle for each cohort you want to sync to FreeWheel.
      </Step>

      <Step title="Verify in FreeWheel">
        After the first sync completes (within 24 hours), check your FreeWheel dashboard to verify that audiences appear with names matching your activated cohorts.
      </Step>
    </Steps>

    <Info>
      Cohort data syncs to FreeWheel daily. Changes to cohort membership will be reflected in FreeWheel within 24 hours of the next scheduled sync.
    </Info>

    <Note>
      Identity Based Activation requires that Permutive is collecting the identity types you select. Work with your Permutive Customer Success Manager to ensure identity collection is configured properly for your desired identity types.
    </Note>
  </Tab>

  <Tab title="iOS">
    Identity Based Activation for iOS enables server-to-server cohort syncing using IDFA (Identifier for Advertisers). No SDK code changes are required on iOS devices.

    **How it works:**

    * Permutive collects IDFA values from iOS users via the Permutive SDK
    * Cohort memberships are synced daily to FreeWheel server-to-server
    * Cohorts appear as Audiences in FreeWheel, ready for campaign targeting
    * Data syncing happens automatically once configured in the Permutive Dashboard

    **Prerequisites:**

    * Permutive SDK must be deployed on your iOS app
    * IDFA collection must be enabled and properly configured
    * Users must grant tracking permission for IDFA to be available
  </Tab>

  <Tab title="Android">
    Identity Based Activation for Android enables server-to-server cohort syncing using AAID (Android Advertising ID). No SDK code changes are required on Android devices.

    **How it works:**

    * Permutive collects AAID values from Android users via the Permutive SDK
    * Cohort memberships are synced daily to FreeWheel server-to-server
    * Cohorts appear as Audiences in FreeWheel, ready for campaign targeting
    * Data syncing happens automatically once configured in the Permutive Dashboard

    **Prerequisites:**

    * Permutive SDK must be deployed on your Android app
    * AAID collection must be enabled and properly configured
  </Tab>

  <Tab title="CTV">
    Identity Based Activation for CTV enables server-to-server cohort syncing using IP Address or other supported identifiers. No SDK code changes are required on CTV devices.

    **How it works:**

    * Permutive collects IP addresses (or other supported identifiers) from CTV users
    * Cohort memberships are synced daily to FreeWheel server-to-server
    * Cohorts appear as Audiences in FreeWheel, ready for campaign targeting
    * Data syncing happens automatically once configured in the Permutive Dashboard

    **Prerequisites:**

    * Permutive must be collecting IP addresses or other supported identifiers from your CTV environment
    * Work with your Permutive Customer Success Manager to ensure proper identity collection for CTV
  </Tab>
</Tabs>

## Data Types

The FreeWheel integration is a Destination-only integration for cohort activation. It does not collect event data from FreeWheel.

<AccordionGroup>
  <Accordion title="Cohort Activation Data (Key-Value)">
    When you activate a cohort to FreeWheel using Key-Value Activation, Permutive creates a Federated Segment in FreeWheel and makes cohort IDs available for targeting via key-value pairs.

    **Cohort ID Format:**

    * Cohort IDs are stored as an array in local storage under the `_pfws` key
    * Each ID corresponds to a cohort the user is a member of
    * Maximum of 250 cohort IDs can be passed per ad request

    **FreeWheel Federated Segment:**

    * Created automatically when a cohort is activated
    * Named using the cohort ID from Permutive
    * Searchable in FreeWheel's audience targeting interface
    * Can be used for campaign targeting (include or exclude)
    * Represents a reusable audience segment across all sites and site sections within your FreeWheel network
  </Accordion>

  <Accordion title="Cohort Activation Data (Identity Based)">
    When you activate a cohort using Identity Based Activation, Permutive uploads audience data enriched with cohort memberships to FreeWheel via a server-to-server transfer.

    **Data Transfer:**

    * Cohort data is synced daily from Permutive to FreeWheel
    * Data is keyed by the identity types you selected during configuration (AAID, IDFA, IP Address)
    * Each user's cohort memberships are associated with their identity values

    **FreeWheel Audiences:**

    * Cohorts appear as Audiences in FreeWheel
    * Named using the cohort name from Permutive
    * Available for campaign targeting in FreeWheel's audience targeting interface
    * Updated daily with the latest cohort membership data
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Unable to enable FreeWheel integration in Permutive Dashboard">
    If you cannot see the FreeWheel integration option in your Permutive Dashboard:

    * Verify that your Permutive Customer Success Manager has enabled the integration for your workspace
    * Confirm that your FreeWheel account manager has allowed Permutive to create Federated Segments in your FreeWheel account
    * Check that your FreeWheel Client ID was provided to Permutive

    Contact your Permutive Customer Success Manager if the integration is still not visible.
  </Accordion>

  <Accordion title="Federated Segments not appearing in FreeWheel">
    If cohorts are activated in Permutive but Federated Segments are not created in FreeWheel:

    * **Client ID**: Verify that the correct FreeWheel Client ID was provided to Permutive
    * **Federated Segments Permission**: Check with your FreeWheel account manager that Permutive has been allowed to create Federated Segments in your FreeWheel account
    * **Cohort Activation**: Ensure the cohort has the FreeWheel activation toggle set to *On* in the Permutive Dashboard

    If the issue persists after checking these items, contact Permutive Support.
  </Accordion>

  <Accordion title="Cohort IDs not available in local storage">
    If you cannot find cohort IDs in local storage (`_pfws` key):

    * **Cohort Activation**: Verify the cohort has the FreeWheel activation toggle set to *On* in the Permutive Dashboard
    * **SDK Deployment**: Ensure the Permutive SDK is properly deployed and loading on your web pages
    * **User Membership**: Confirm the current user is actually a member of the activated cohort (check in browser console using `permutive.segments()`)
    * **Browser Console**: Open browser console and check `window.localStorage._pfws` to see if the key exists

    If the key exists but is empty, the user may not be in any activated cohorts.
  </Accordion>

  <Accordion title="Cohorts not being passed to FreeWheel ad requests">
    If cohort IDs are in local storage but not appearing in your FreeWheel ad requests:

    * **Implementation**: Verify you've implemented the code to retrieve cohort IDs from local storage (see Web Setup tab)
    * **Timing**: Ensure the Permutive SDK loads before you attempt to retrieve cohort IDs
    * **Ad Request Configuration**: Check that your ad request code is correctly appending the cohort variable to FreeWheel ad calls
    * **Network Inspection**: Use browser developer tools to inspect network requests to FreeWheel and verify cohort IDs are included

    For implementation assistance, contact Permutive Support.
  </Accordion>

  <Accordion title="Cohorts not appearing in SDK APIs (iOS/Android)">
    If cohort IDs are not being returned by the SDK APIs:

    * **Cohort Activation**: Verify the cohort has the FreeWheel activation toggle set to *On* in the Permutive Dashboard
    * **SDK Deployment**: Ensure the Permutive SDK is properly deployed and initialized in your app
    * **Activation Type**: Verify you're using the correct activation type key (`freewheel`)
    * **User Membership**: Confirm the current user is a member of the activated cohort

    For iOS, check the `activations` property. For Android, ensure the `TriggersProvider` callback is properly set up with activation type `freewheel`.
  </Accordion>

  <Accordion title="API Direct returning empty activations">
    If the CCS API response includes an empty `freewheel` array or doesn't include the key at all:

    * **Integration Enabled**: Verify the FreeWheel integration is enabled in the Permutive dashboard
    * **Cohort Activation**: Check that cohorts have been activated for FreeWheel
    * **User Membership**: Ensure the user identified in the API request (via `alias`) is a member of activated cohorts
    * **Query Parameter**: Confirm the `activations=true` query parameter is included in the API request URL
    * **API Key**: Verify the API key used in the request has the correct permissions

    For API Direct issues, contact your Permutive Customer Success Manager for assistance.
  </Accordion>

  <Accordion title="Need to update Client ID">
    If you need to update your FreeWheel Client ID:

    * Contact your Permutive Customer Success Manager with the new Client ID
    * Permutive will update the configuration for your integration

    Do not attempt to update the Client ID directly - always work with your Customer Success Manager.
  </Accordion>

  <Accordion title="Issues with Identity Based Activation">
    If you're experiencing issues with Identity Based Activation:

    * **Missing Audiences**: Verify that cohorts are activated with the "FreeWheel (ID-based)" toggle enabled in the Permutive Dashboard
    * **Sync Timing**: Remember that cohort data syncs daily - allow up to 24 hours for changes to appear in FreeWheel
    * **Identity Collection**: Confirm that Permutive is collecting the identity types you selected (AAID, IDFA, IP Address) by checking with your Permutive Customer Success Manager
    * **Configuration**: Verify your FreeWheel Client ID and selected identity types are correct in Settings → Integrations

    For Identity Based Activation issues, contact your Permutive Customer Success Manager for assistance.
  </Accordion>
</AccordionGroup>

## Changelog

### January 2026

* Added Identity Based Activation support for all environments
* Identity Based Activation enables server-to-server cohort upload keyed by AAID, IDFA, or IP Address
* Cohorts activated via Identity Based Activation appear as Audiences in FreeWheel

### November 2025

* Documentation updated to clarify that the integration uses FreeWheel Federated Segments

### January 2023

* Initial release of FreeWheel integration for cohort activation

<Info>
  For detailed changelog information, visit our [Changelog](https://changelog.permutive.com/).
</Info>