krolewskie-miody.pl/wp-content/plugins/facebook-for-woocommerce/vendor/facebook/capi-param-builder-php/php

Conversions API parameter builder feature for PHP

Introduction

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

Server-Side Parameter Builder Onboarding Guide

Quick start

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

Setup

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.

Demo

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.

API usage

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. Call processRequest to process fbc, fbp and fbi(client_ip_address).

$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->processRequest(...)

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, normalized and hashed PII values

$fbc = $param_builder->getFbc();

$fbp = $param_builder->getFbp();

$client_ip_address = $param_builder->getClientIpAddress();

$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 fbc, fbp, client_ip_address, email and phone back through Conversions API.

data=[
 'event_name: '...',
 'event_time': <your_time>,
 '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
     ...
 }
 ...
]

License

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