Setup
Troubleshooting
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.
- 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
Prerequisites
- Facebook Pixel: You must have the Facebook pixel already installed and active on your website. Verify this by searching for
_fbqin 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.
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.
Setup
- Primary Setup Steps
- Web
1
Verify Facebook Pixel Installation
Before enabling the Permutive integration, verify that the Facebook pixel is properly installed on your site:
- Open your website in a browser
- Open Developer Tools (F12 or right-click → Inspect)
- In the Console tab, search for
_fbq - If the Facebook pixel is installed, you should see the
_fbqobject defined - If you see an error message that
_fbqis not defined, please refer to the Facebook pixel implementation documentation and contact Facebook support if needed
You can also use the Meta Pixel Helper Chrome extension to verify pixel installation.
2
Add Integration in Permutive Dashboard
- Navigate to Settings > Integrations in the Permutive Dashboard
- Click + Add Integration
- Select Facebook Pixel from the list of available integrations
- You will see a configuration screen where you need to select your Facebook account type
3
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: Once you have selected your Facebook account type, click Add Integration.
PermutiveSegmentEntry_<CohortCode> and PermutiveSegmentExit_<CohortCode>. For example, if a user is segmented into Permutive cohort 123, the following pixel event will fire: PermutiveSegmentEntry_123Non-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.Your account administrator or Facebook representative will be able to confirm what type of account you have.
4
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.
5
Configure Cohort Activations
For each cohort you want to activate to Facebook:
- Navigate to the cohort in the Permutive dashboard
- In the Activation Syncs section, toggle the Facebook Pixel activation to On
- The cohort will now be sent to Facebook when users enter or exit the cohort
6
Verify Setup
To verify that cohorts are being sent to Facebook:
- Use the Meta Pixel Helper Chrome extension to monitor pixel events on your site
- For Core Setup accounts, look for custom events named
PermutiveSegmentEntry_<CohortCode>when users enter cohorts - For Non-Core Setup accounts, look for events named
PermutiveSegmentEntrywith asegment_idproperty - In Facebook Business Manager, check that custom audiences are being populated with data from the pixel events
Data Types
With your Facebook integration setup, Permutive fires custom events to your Meta pixel to enable audience building:PermutiveSegmentEntry (Non-Core Setup)
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.
PermutiveSegmentExit (Non-Core Setup)
PermutiveSegmentExit (Non-Core Setup)
PermutiveSegmentEntry_<CohortCode> (Core Setup)
PermutiveSegmentEntry_<CohortCode> (Core Setup)
PermutiveSegmentExit_<CohortCode> (Core Setup)
PermutiveSegmentExit_<CohortCode> (Core Setup)
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.
Troubleshooting
Facebook pixel events not appearing in Meta Pixel Helper
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
PermutiveSegmentEntryevents with asegment_idproperty - For Core Setup accounts, look for
PermutiveSegmentEntry_<CohortCode>events
Custom audiences not populating in Facebook Business Manager
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
PermutiveSegmentEntrycustom event with the correctsegment_idvalue - 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.
Multiple Facebook pixels receiving Permutive data
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
fbq("trackCustom", ...), which Meta delivers to every pixel initialised on the page, and there is no Permutive setting to limit this. To stop a pixel receiving Permutive data, don’t initialise that pixel on pages where the Permutive SDK runs.Incorrect account type selected during setup
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:
- Verify your Facebook account type with your account administrator or Facebook representative
- Core Setup accounts require unique events per cohort (
PermutiveSegmentEntry_<CohortCode>) - Non-Core Setup accounts use generalized events with a
segment_idproperty (PermutiveSegmentEntry) - If you selected the wrong account type, you will need to remove and re-add the Facebook integration with the correct configuration
- Contact Permutive Support if you need assistance reconfiguring the integration
Changelog
October 2024
- Enhanced configuration options for Meta Core Setup accounts to support separate custom events per cohort
For detailed changelog information, visit our
Changelog.