The Conversions API parameter builder SDK is a lightweight tool for improving Conversions API parameter retrieval and quality.

Server-Side Parameter Builder Onboarding Guide

Here is a quick-start guide for integrating the parameter builder feature into your code. You can find a demo in the next section.

1. Check the latest version in CHANGELOG. Modify below {current_version} into latest version number.

2. Update in your composer.json with the latest version.

"require": {
       "php": ">=7.4",
       "facebook/capi-param-builder-php": "{current_version}"
   },

3. Install the dependency. If you don't have an application, check #demo section for a demo application.

composer install

or update if you need to update the version.

composer update

Once you finish these steps, the setup step of your parameter builder integration is complete. You can see a demo in the following section.

Here is a demo application on your localhost. If you've already familiar with the library, feel free to skip this section.

1. Checkout the examples for localhost demo and Drupal demo under ./examples

2. Take localhost as an example, go to ./examples/local. Install or update the dependency by running

 composer install
 or
 composer update

3. Start the server

php -S localhost:8000

4. Visit http://localhost:8000/demo.php for the localhost demo webpage. Accept the cookie consent at the bottom of the page to continue. You'll see the main page with fbc and fbp value printed.

Following are some further validations:

4.1 Go to http://localhost:8000/demo.php?fbclid=thisIsATest123. The printed fbc and fbp should be present and not null. The printed fbc should have a portion containing thisIsATest123. Please also validate that the corresponding respective cookie values, ‘_fbc’ and ‘_fbp’, are the same as printed fbc and fbp.

4.2 Go to http://localhost:8000/demo.php. Please validate that printed fbc and fbpand corresponding cookie values, ‘_fbc’ and ‘_fbp’ are the same as those in step 4.1.

This section explains how to use the APIs provided in the SDK.

1. Integrate the library as #Quick start section mentioned above.
2. Import the parameter builder and build the constructor. The ETLD+1 can help you get the recommended domain to save cookies.

Option 1 (recommended): input ELTD+1 domain list. We'll compare your current host name and provide the domain we recommended to save your cookie.

 $param_builder = new FacebookAds\ParamBuilder(array('example.com', 'test.com'));

Option 2: Customized ETLD+1 resolver. Create a file implementing ETLDPlus1Resolver. Example: ETLDPlus1ResolverForTest.php under ./examples/local.

 $param_builder = new FacebookAds\ParamBuilder(new ETLDPlus1ResolverForTest());

Option 3: Not recommended. We'll do a simple check to return one level down subdomain. Eg. your input is test.example.demo.com, we'll return example.demo.com. This option may be less accurate.

 $param_builder = new FacebookAds\ParamBuilder();

3. [Recommended] Call processRequestFromContext to process fbc, fbp, client_ip_address, event_source_url and referrer_url. Pass your framework's request context (or null to read from the $_SERVER / $_COOKIE / $_GET superglobals) — the SDK extracts host / cookies / query / referer (and the request URI for event_source_url) for you, and returns the recommended cookies to set. See the Framework support section for exactly what to pass for your framework.

$cookie_to_set = $param_builder->processRequestFromContext(); // reads from $_SERVER

Deprecated: processRequest is still supported but deprecated. It does not construct event_source_url. Prefer processRequestFromContext above.

$param_builder->processRequest(
   $host_name, // string for full url
   $url_query_params, // map for query params
   $cookie, // map for cookies
   $referral_link, // (optional, nullable)string, full referral link to help improve potential event quality.
   $x_forwarded_for, // (optional, nullable)string, the http x_forwarded_for request header.
   $remote_address // (optional, nullable)string, the remote_address variable in http request.
);

4. [Recommended] Save the $cookie_to_set as first-party cookies to keep fbc and fbp consistent across all events. Based on your webserver framework, the save cookie API may vary. Feel free to choose the best fit for your use case. Below is one example excerpted from the demo application.

Recommended: get $cookie_to_set from API call in step 3.

$cookie_to_set = $param_builder->processRequestFromContext();

Optional: getCookiesToSet API

$cookie_to_set = $param_builder->getCookiesToSet()

Call setcookie from the server side to have the cookies saved.

foreach ($cookie_to_set as $cookie) {
 setcookie(
   $cookie->name,
   $cookie->value,
   time() + $cookie->max_age,
   '/',
   $cookie->domain);
}

If there is no change to your current cookies, the returned list will be empty.

5. Get fbc/fbp, client_ip_address, event_source_url, referrer_url, normalized and hashed PII values

$fbc = $param_builder->getFbc();

$fbp = $param_builder->getFbp();

$client_ip_address = $param_builder->getClientIpAddress();

$event_source_url = $param_builder->getEventSourceUrl();

$referrer_url = $param_builder->getReferrerUrl();

$email = $param_builder->getNormalizedAndHashedPII(' John_Smith@gmail.com','email');

$phone = $param_builder->getNormalizedAndHashedPII('+1 (616) 954-78 88','phone');

getNormalizedAndHashedPII(piiValue, dataType)

API is to get normalized and hashed (sha256) PII from input piiValue, supported dataType include 'phone', 'email', 'first_name', 'last_name', 'date_of_birth', 'gender', 'city', 'state', 'zip_code', 'country' and 'external_id'.

6. Send the parameters back to the Conversions API. event_source_url and referrer_url are sent at the event level; fbc, fbp, client_ip_address, em (email) and ph (phone) are sent inside user_data.

data=[
 'event_name': '...',
 'event_time': <your_time>,
 'event_source_url': $event_source_url, // The value provided in step 5
 'referrer_url': $referrer_url, // The value provided in step 5
 'user_data': {
   'fbc': $fbc, // The value provided in step 5
   'fbp': $fbp, // The value provided in step 5
   'client_ip_address': $client_ip_address // The value provided in step 5
   'em': $email // The value provided in step 5
   'ph': $phone // The value provided in step 5
     ...
 }
 ...
]

$param_builder->processRequestFromContext($context) accepts an environ-style array and extracts host / cookies / query / referer for you. It supports out of the box:

• null (reads from $_SERVER / $_COOKIE / $_GET superglobals)
• Any associative array shaped like $_SERVER (with HTTP_HOST, HTTP_COOKIE, QUERY_STRING, etc.)

Frameworks that need a small adjustment:

• Symfony / Laravel — pass the framework's server bag, not the Request object itself:

  $param_builder->processRequestFromContext($request->server->all());

• Slim / other PSR-7 — pass $request->getServerParams().

For any other framework, you can build a PlainDataObject directly and pass it in, or fall back to the original processRequest($host, $queries, $cookies, $referer) call.

The SDK can extract event_source_url and referrer_url from the incoming HTTP request. These values help improve Conversions API event matching and attribution quality.

Using processRequestFromContext (recommended):

$param_builder->processRequestFromContext(); // reads from $_SERVER automatically

$event_source_url = $param_builder->getEventSourceUrl();
$referrer_url = $param_builder->getReferrerUrl();

Using processRequest (deprecated):

processRequest does not construct event_source_url — only referrer_url is available via the referer parameter. Use processRequestFromContext if you need event_source_url.

Send them with your Conversions API payload:

$data = [
    'event_name' => '...',
    'event_time' => time(),
    'event_source_url' => $param_builder->getEventSourceUrl(),
    'referrer_url' => $param_builder->getReferrerUrl(),
    'user_data' => [
        'fbc' => $param_builder->getFbc(),
        'fbp' => $param_builder->getFbp(),
        'client_ip_address' => $param_builder->getClientIpAddress(),
    ],
];

The Conversions API parameter builder feature for PHP is licensed under the LICENSE file in the root directory of this source tree.