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

# Facebook

> Activate Permutive cohorts to Facebook for custom audience targeting

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/pNhz39ducTVcQczh/images/integrations/logos/facebook.svg?fit=max&auto=format&n=pNhz39ducTVcQczh&q=85&s=45ed5f3a6497104730dc95c4715a01b2" alt="Facebook" style={{ maxWidth: '32px', maxHeight: '32px', display: 'block' }} width="2084" height="2084" data-path="images/integrations/logos/facebook.svg" />
    </div>

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

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

    <BadgeRowCenter label="Environment">
      <BadgeContainer>
        <EnvironmentBadge environment="Web" />
      </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",
}}
  >
    Activate Permutive cohorts to Facebook for custom audience targeting and
    advertising campaigns.
  </p>
</Card>

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

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

## Overview

The Permutive Facebook Pixel integration enables you to send rich cohort information to Facebook in real-time for audience targeting. These audiences are passed to Facebook via custom pixel events and can be used to build custom audiences in Facebook Ads Manager.

This integration is a Destination:

* **Destination:** Permutive sends cohort membership data to Facebook via the Facebook pixel, enabling you to build custom audiences based on Permutive cohorts.

Use cases include:

* Build custom audiences in Facebook Ads Manager based on your Permutive cohorts
* Retarget users across Facebook, Instagram, and Meta Audience Network
* Target users with precision using real-time cohort membership data
* Create lookalike audiences based on Permutive cohorts

## Environment Compatibility

| Environment    | Supported    | Notes                                 |
| -------------- | ------------ | ------------------------------------- |
| **Web**        | <YesBadge /> | Requires Meta pixel installed on site |
| **iOS**        | <NoBadge />  | --                                    |
| **Android**    | <NoBadge />  | --                                    |
| **CTV**        | <NoBadge />  | --                                    |
| **API Direct** | <NoBadge />  | --                                    |

## Prerequisites

* **Facebook Pixel:** You must have the Facebook pixel already installed and active on your website. Verify this by searching for `_fbq` in the browser console. The Permutive SDK integrates with the existing Facebook pixel implementation to send cohort membership data.
* **Facebook Business Manager Access:** You should have access to your Facebook Business Manager account to view and manage custom audiences created from Permutive cohorts.
* **Facebook Account Type:** Your Facebook account administrator or Facebook representative should confirm whether you have a Core Setup or Non-Core Setup account, as this determines the pixel event configuration.
* **Permutive SDK:** The Permutive Web SDK must be deployed on your site. The Facebook integration is an add-on that works with the core Permutive SDK.

<Note>
  The Facebook pixel integration works by firing custom events to the Facebook
  pixel SDK that is already present on your page. Permutive does not install the
  Facebook pixel for you. The integration automatically works with multiple Facebook
  pixels on your site.
</Note>

## Setup

<Tabs>
  <Tab title="Primary Setup Steps">
    <Steps>
      <Step title="Verify Facebook Pixel Installation">
        Before enabling the Permutive integration, verify that the Facebook pixel is properly installed on your site:

        1. Open your website in a browser
        2. Open Developer Tools (F12 or right-click → Inspect)
        3. In the Console tab, search for `_fbq`
        4. If the Facebook pixel is installed, you should see the `_fbq` object defined
        5. If you see an error message that `_fbq` is not defined, please refer to the [Facebook pixel implementation documentation](https://www.facebook.com/business/help/952192354843755) and contact Facebook support if needed

        <Note>
          You can also use the [Meta Pixel Helper Chrome extension](https://chrome.google.com/webstore/detail/meta-pixel-helper/fdgfkebogiimcoedlicjlajpkdmockpc) to verify pixel installation.
        </Note>
      </Step>

      <Step title="Add Integration in Permutive Dashboard">
        1. Navigate to **Settings > Integrations** in the Permutive Dashboard
        2. Click **+ Add Integration**
        3. Select **Facebook Pixel** from the list of available integrations
        4. You will see a configuration screen where you need to select your Facebook account type
      </Step>

      <Step title="Select Facebook Account Type">
        Depending on the type of Facebook account you have, select either **Core Setup** or **Non-Core Setup**. This configuration determines the type of pixel event that will be sent by the Facebook pixel.

        **Core Setup:** If you have a Core Setup Facebook account, you will see two unique pixel events collected for every cohort: `PermutiveSegmentEntry_<CohortCode>` and `PermutiveSegmentExit_<CohortCode>`. For example, if a user is segmented into Permutive cohort 123, the following pixel event will fire: `PermutiveSegmentEntry_123`

        **Non-Core Setup:** If you have a Non-Core Setup Facebook account, you will see two generalized pixel events for all cohorts — only one event named `PermutiveSegmentEntry` will represent all cohort entries and only one event named `PermutiveSegmentExit` will represent all cohort exits. An event property named `segment_id` stored within each of those generalized events will contain the Permutive cohort code.

        <Note>
          Your account administrator or Facebook representative will be able to confirm what type of account you have.
        </Note>

        Once you have selected your Facebook account type, click **Add Integration**.
      </Step>

      <Step title="Wait for Integration to Activate">
        The integration will be available for use in under 20 minutes. Once activated, you can begin sending cohorts to Facebook.
      </Step>

      <Step title="Configure Cohort Activations">
        For each cohort you want to activate to Facebook:

        1. Navigate to the cohort in the Permutive dashboard
        2. In the Activation Syncs section, toggle the Facebook Pixel activation to *On*
        3. The cohort will now be sent to Facebook when users enter or exit the cohort
      </Step>

      <Step title="Verify Setup">
        To verify that cohorts are being sent to Facebook:

        1. Use the Meta Pixel Helper Chrome extension to monitor pixel events on your site
        2. For Core Setup accounts, look for custom events named `PermutiveSegmentEntry_<CohortCode>` when users enter cohorts
        3. For Non-Core Setup accounts, look for events named `PermutiveSegmentEntry` with a `segment_id` property
        4. In Facebook Business Manager, check that custom audiences are being populated with data from the pixel events
      </Step>
    </Steps>

    <Expandable title="Advanced: Understanding Core Setup vs Non-Core Setup">
      ### Core Setup vs Non-Core Setup

      The Facebook account type you select during integration setup determines how Permutive sends cohort data to Facebook:

      **Core Setup Accounts:**

      * Send unique pixel events for each cohort
      * Event naming format: `PermutiveSegmentEntry_<CohortCode>` and `PermutiveSegmentExit_<CohortCode>`
      * Example: A user entering cohort 123 fires the event `PermutiveSegmentEntry_123`
      * This approach is required because Core Setup accounts do not collect custom parameters in pixel events

      **Non-Core Setup Accounts:**

      * Send generalized pixel events for all cohorts
      * Event names: `PermutiveSegmentEntry` and `PermutiveSegmentExit`
      * The specific cohort code is passed as a property named `segment_id` within the event
      * This allows for more efficient event tracking across multiple cohorts

      <Note>
        In a Meta Pixel context, "Core Setup" is a data restriction mode that Meta automatically or manually applies to a pixel when a website is identified as being in a sensitive industry (e.g., healthcare, financial services) or has violated data-sharing terms. When a pixel is in Core Setup, Meta limits the type and amount of data it collects to reduce the potential for sharing prohibited information.
      </Note>
    </Expandable>

    <Expandable title="Advanced: Multiple Facebook Pixels">
      ### Working with Multiple Facebook Pixels

      This integration works seamlessly with multiple Facebook pixels on your site. Permutive will automatically detect whichever Facebook pixel is available on the page for the domain where it is running.

      **How it works:**

      For example, if `https://www.sport.com/` has a pixel with one account ID and `https://www.gamebyte.com/` has a pixel with a different account ID:

      * When a cohort in your project is sent to Facebook, users who entered that cohort from `https://www.sport.com/` will be sent to the associated Facebook account
      * Users who entered the segment from `https://www.gamebyte.com/` will be sent to the associated Facebook account

      The integration automatically routes cohort data to the correct Facebook pixel based on the domain.

      **Selective Pixel Firing:**

      If you want to control which specific pixels receive Permutive cohort activations:

      <Note>
        This feature is available on request. Contact your Customer Success Manager to
        enable selective pixel firing for your workspace.
      </Note>

      Once enabled, you can:

      1. Configure a list of pixel IDs in your Facebook integration settings
      2. Toggle cohort activations per pixel when creating or editing activations
      3. Control precisely which pixels receive which cohort activations

      This is useful if you deploy pixels for different purposes (e.g., agency pixels, partner pixels) and don't want to send Permutive cohorts to all of them.
    </Expandable>
  </Tab>

  <Tab title="Web">
    ### Web Implementation

    The Facebook pixel integration works automatically once enabled in the dashboard. The Permutive SDK fires custom events to the Facebook pixel when users enter or exit cohorts that are configured for Facebook activation.

    The integration automatically detects and works with all Facebook pixels on your site, sending cohort data to the appropriate pixel based on the domain.

    ### Technical Details

    The event structure depends on your Facebook account type:

    **Non-Core Setup Accounts:**

    When a user enters a cohort configured for Facebook activation:

    ```javascript theme={"dark"}
    fbq("trackCustom", "PermutiveSegmentEntry", {
      segment_id: "<COHORT_CODE>",
    });
    ```

    When a user exits a cohort:

    ```javascript theme={"dark"}
    fbq("trackCustom", "PermutiveSegmentExit", {
      segment_id: "<COHORT_CODE>",
    });
    ```

    **Core Setup Accounts:**

    When a user enters cohort 123:

    ```javascript theme={"dark"}
    fbq("trackCustom", "PermutiveSegmentEntry_123");
    ```

    When a user exits cohort 123:

    ```javascript theme={"dark"}
    fbq("trackCustom", "PermutiveSegmentExit_123");
    ```

    These events are captured by Facebook and can be used to build custom audiences in Facebook Business Manager.
  </Tab>
</Tabs>

## Data Types

With your Facebook integration setup, Permutive fires custom events to your Meta pixel to enable audience building:

<AccordionGroup>
  <Accordion title="PermutiveSegmentEntry (Non-Core Setup)">
    Custom event fired when a user enters a cohort that has Facebook activation
    enabled. This event is used by Facebook to build custom audiences.

    <ResponseField name="event_name" type="string">
      The custom event name: `PermutiveSegmentEntry`
    </ResponseField>

    <ResponseField name="segment_id" type="string">
      The Permutive cohort code that the user entered. This property contains
      the unique identifier for the cohort.
    </ResponseField>
  </Accordion>

  <Accordion title="PermutiveSegmentExit (Non-Core Setup)">
    Custom event fired when a user exits a cohort that has Facebook activation
    enabled.

    <ResponseField name="event_name" type="string">
      The custom event name: `PermutiveSegmentExit`
    </ResponseField>

    <ResponseField name="segment_id" type="string">
      The Permutive cohort code that the user exited.
    </ResponseField>
  </Accordion>

  <Accordion title="PermutiveSegmentEntry_<CohortCode> (Core Setup)">
    For Core Setup accounts, a unique custom event is fired for each cohort when
    a user enters that cohort.

    <ResponseField name="event_name" type="string">
      The custom event name: `PermutiveSegmentEntry_[COHORT_CODE]` where
      `[COHORT_CODE]` is the unique identifier for the cohort. For example:
      `PermutiveSegmentEntry_123`
    </ResponseField>
  </Accordion>

  <Accordion title="PermutiveSegmentExit_<CohortCode> (Core Setup)">
    For Core Setup accounts, a unique custom event is fired for each cohort when
    a user exits that cohort.

    <ResponseField name="event_name" type="string">
      The custom event name: `PermutiveSegmentExit_[COHORT_CODE]` where
      `[COHORT_CODE]` is the unique identifier for the cohort. For example:
      `PermutiveSegmentExit_123`
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  Custom events sent to Facebook are subject to Facebook's data processing and
  matching. Match rates depend on Facebook's ability to match users based on
  cookies and other identifiers. Third-party cookies may be blocked in some
  environments, which can affect match rates.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Facebook pixel events not appearing in Meta Pixel Helper">
    First, verify that the Facebook pixel is properly installed on your site by checking that `_fbq` is defined in the browser console. If the pixel is installed but Permutive events are not appearing:

    * Check that the Facebook integration is enabled in the Permutive dashboard and has been active for at least 20 minutes
    * Verify that cohorts are configured with Facebook activation enabled
    * Ensure that the Permutive SDK has loaded successfully on the page
    * Check the browser console for any JavaScript errors that might be preventing the Permutive SDK from executing
    * For Non-Core Setup accounts, look for `PermutiveSegmentEntry` events with a `segment_id` property
    * For Core Setup accounts, look for `PermutiveSegmentEntry_<CohortCode>` events
  </Accordion>

  <Accordion title="Custom audiences not populating in Facebook Business Manager">
    Facebook custom audiences built from pixel events can take 24-48 hours to populate after pixel events start firing. If audiences are still not populating after this time:

    * Verify that pixel events are firing correctly using the Meta Pixel Helper
    * Check that the pixel ID in your pixel implementation matches the pixel ID in Facebook Business Manager
    * For Non-Core Setup accounts, ensure your custom audience definition in Facebook includes the `PermutiveSegmentEntry` custom event with the correct `segment_id` value
    * For Core Setup accounts, ensure your custom audience definition includes the specific `PermutiveSegmentEntry_<CohortCode>` event
    * Check Facebook's Event Match Quality score, which indicates how well Facebook can match pixel data to Facebook users. Low match quality may be due to cookie blocking or other privacy restrictions.
  </Accordion>

  <Accordion title="Multiple Facebook pixels receiving Permutive data">
    By default, Permutive automatically detects and works with all Facebook pixels on your site. The integration will pick up whichever Facebook pixel is available on the page for the domain where it is running. This means:

    * Different domains with different pixel IDs will automatically send data to their respective Facebook accounts
    * Users who enter a cohort from one domain will be sent to that domain's associated Facebook account
    * Users who enter a cohort from another domain will be sent to that domain's associated Facebook account

    If you want to control which specific pixels receive Permutive data, this requires custom configuration. Please contact your Customer Success Manager to discuss options for selective pixel activation.
  </Accordion>

  <Accordion title="Third-party cookie blocking affecting match rates">
    Facebook uses third-party cookies for user matching, which are increasingly blocked by browsers and privacy tools. If you're experiencing low match rates:

    * Consider using Facebook's Conversion API for server-side data transfer (contact Permutive Support for guidance)
    * Ensure users are logged into Facebook when visiting your site, as this improves matching
    * Review Facebook's Event Match Quality metrics in Facebook Business Manager to understand matching performance
  </Accordion>

  <Accordion title="Incorrect account type selected during setup">
    If you selected the wrong account type (Core Setup vs Non-Core Setup) during integration setup and cohort data isn't appearing in Facebook:

    1. Verify your Facebook account type with your account administrator or Facebook representative
    2. Core Setup accounts require unique events per cohort (`PermutiveSegmentEntry_<CohortCode>`)
    3. Non-Core Setup accounts use generalized events with a `segment_id` property (`PermutiveSegmentEntry`)
    4. If you selected the wrong account type, you will need to remove and re-add the Facebook integration with the correct configuration
    5. Contact Permutive Support if you need assistance reconfiguring the integration
  </Accordion>
</AccordionGroup>

## Changelog

### April 2025

* Added support for selective pixel firing to control which Meta pixels receive Permutive activations

### October 2024

* Enhanced configuration options for Meta Core Setup accounts to support separate custom events per cohort

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