How can we help you?

The Gravity Forms + Facebook Conversion Integration Add-on connects your WordPress forms directly to Meta’s Server-Side Conversions API (CAPI) and client-side Meta Pixel. In today’s privacy-focused landscape—shaped by Apple’s iOS 14.5+ App Tracking Transparency (ATT), Safari ITP, aggressive browser ad-blockers, and third-party cookie deprecation—browser-only pixels lose up to 40% of conversion data. This add-on restores 100% data fidelity by dispatching encrypted server-to-server events with automated SHA-256 customer data hashing, real-time event deduplication, and complete Gravity Forms conditional logic support.

Core Features & Architecture

Built on the official Gravity Forms Add-on Framework and Meta PHP Business SDK, this integration provides an enterprise-grade tracking bridge between WordPress and Meta Ads Manager:

Prerequisites & Meta Business Setup

Before configuring the plugin in WordPress, ensure you have gathered the required credentials from your Meta Business Suite:

1. Meta Pixel ID: Navigate to Meta Events Manager > Data Sources. Select your dataset/pixel and copy the 15–16 digit Pixel ID from the Settings tab.
2. Conversions API System User Access Token: In Business Settings > Users > System Users, create an Admin System User, assign your Pixel with Manage Pixel permissions, and generate a 60-day or permanent Access Token with the ads_management permission.
   💡 Pro-Tip: Permanent Access Token

   Never use a temporary token generated from the Graph API Explorer; it expires after 1–2 hours. Always generate your token via a System User in Meta Business Settings for 24/7 uninterrupted tracking.

3. Verified Domain: Ensure your website domain is verified under Business Settings > Brand Safety > Domains to comply with Meta Aggregated Event Measurement rules.

Figure 1: Meta Events Manager — Locating your Pixel / Dataset ID in Settings.

Figure 2: Meta Events Manager — Generating and copying your System User Access Token.

Step-by-Step Installation & Configuration Guide

Step 1: Installation & License Activation

1. Download the plugin ZIP file from your GravityExtra Account Downloads page.
2. In WordPress Admin, go to Plugins > Add New > Upload Plugin, choose gravityextra-gf-facebook-conversion-addon.zip, and click Install Now > Activate Plugin.
3. Navigate to Forms > Settings > Facebook Conversion Add-on. Enter your License Key and click Save Settings to activate automatic updates and premium features.

Step 2: Global Meta CAPI Settings

Navigate to Forms > Settings > Facebook Conversion Add-on:

• Pixel ID: Paste your Meta Dataset / Pixel ID.
• Access Token: Paste the System User Conversions API Access Token generated in Meta Business Settings.
• Enable pixel code on front end of website:
  • Checked (Default): Recommended if you do not have Facebook Pixel installed. The add-on will automatically inject fbevents.js, fire base PageView events, and synchronize event_id deduplication cookies (_fbp, _fbc).
  • Unchecked: If you already deploy Meta Pixel via Google Tag Manager (GTM) or PixelYourSite, leave this unchecked to prevent duplicate base scripts. The add-on will seamlessly hook into existing browser cookies for server CAPI deduplication.

Figure 3: Gravity Forms Global Settings — Configuring Pixel ID, Access Token, and frontend pixel code.

Step 3: Creating a Form Conversion Feed

Once global settings are saved, connect individual forms to Meta:

1. Go to Forms, hover over your target form, and click Settings > Facebook Conversion.
2. Click Add New to create a new conversion feed.
3. Feed Name: Provide an administrative identifier (e.g. Qualified B2B Lead Conversion).
4. Event Name: Select the primary conversion event:
   • Lead: Standard form inquiries, quote requests, demo bookings.
   • CompleteRegistration: User signup, webinar registration, account creation.
   • Purchase: Order forms with payment processing.
   • Contact: General inquiries or support tickets.
   • Custom Event: Specify any custom event name for granular tracking.
5. Action Source: Select website (conversions happening on your WordPress pages).
6. Event ID (Prefix): Enter an optional alphanumeric prefix (e.g. lead_ or gf_). The add-on automatically combines this prefix with the submission timestamp to create a universally unique event_id for deduplication.
7. Event Source URL: Provide the page URL where the conversion took place (must begin with https://).

Figure 4: Facebook Conversion Feeds Manager — Creating a new conversion tracking feed.

Figure 5: Feed Configuration Studio — Defining event name, action source, and event ID prefix.

Step 4: Mapping Customer Data (Advanced Matching)

High Event Match Quality (EMQ) is the single most critical factor for Meta ad delivery optimization. In the Map Fields section, map your form fields to Meta user parameters:

Figure 6: Customer Information Field Mapping — Associating form inputs with user data parameters for SHA-256 hashing.

Step 5: Transaction Value & Dynamic Currency

For e-commerce order forms, donation widgets, or lead forms with estimated budget sizes:

1. Check Includes value of the transaction field.
2. Currency: Select standard ISO currency (e.g. USD, EUR, GBP, AUD).
3. Value: Choose a static numerical amount, map a Gravity Forms Pricing/Total field, or insert dynamic merge tags (e.g. {Total:5}). The add-on automatically strips currency symbols and decimals to format clean floats for Meta.

Figure 7: Currency & Value Configuration — Setting conversion transaction values and ISO currency codes.

Step 6: Conditional Logic Routing

Prevent spam or unqualified submissions from corrupting your Meta Ads algorithm:

• Enable Conditional Logic inside the feed settings.
• Configure rules such as: “Send this feed if ‘Project Budget’ is greater than ‘$1,000′” or “Send this feed if ‘Are you an enterprise customer?’ is ‘Yes'”.
• You can configure multiple feeds on the same form to fire different events based on user input (e.g. Lead for standard contacts, and Schedule for high-intent enterprise users).

Figure 8: Conditional Logic Routing — Triggering conversion events based on form response values.

Live Testing & Verification in Meta Events Manager

Verifying that your server-side conversions are arriving correctly is simple with Meta’s built-in Test Events tool:

1. In Meta Events Manager, go to Test Events.
2. Under Confirm your server events are set up correctly, copy the unique Test Event Code (e.g. TEST12345).
3. Open your Gravity Forms Facebook Conversion feed settings in WordPress, paste the code into the Test Event Code field, and click Update Settings.
4. Submit a test entry on your live WordPress form.
5. Return to Meta Events Manager. You will immediately observe the event appearing in the real-time stream:
   • Source: Server (Conversions API).
   • Status: Success.
   • Deduplication Status: If both browser pixel and server CAPI are active, Meta displays both entries bundled together with identical Event ID and flags them as Deduplicated.
6. CRITICAL: Once verified, delete the Test Event Code from the feed settings and save. Never leave test event codes active in production, as live ad attribution will be paused while test codes are present.

Figure 9: Meta Events Manager Test Events — Copying Test Event Code for real-time verification.

Developer Guide: Custom Hooks & Filter Architecture

Developers can customize the payload before transmission or programmatically bypass tracking for internal team members:

Bypass Conversion Tracking for Site Administrators

Add this filter to your child theme’s functions.php or custom mu-plugin to prevent administrator submissions from polluting Meta ad conversion data:

/**
 * Bypass Facebook Conversions API for Administrator submissions
 * Prevents internal testing from skewing Meta Ads ROAS data
 */
add_filter( 'gform_facebook_conversion_feed_is_active', function( $is_active, $feed, $entry, $form ) {
    // Bypass if the logged-in user is an administrator
    if ( current_user_can( 'manage_options' ) ) {
        return false;
    }

    return $is_active;
}, 10, 4 );

Troubleshooting & Frequently Asked Questions