Conversions API

Parameter Builder Library: Client-Side Onboarding Guide

Meta has provided a list of library SDKs in both client-side (JavaScript) and server-side (PHP, Java, Python, NodeJS, Ruby). These SDK libraries are intended to help developers improve the quality of Conversions API event parameters (for example, fbc, fbp, client_ip_address and other customer information parameters like em and ph), and enable advertisers to adhere to Meta’s best practices around generating these parameters.

Currently, the parameter builder feature manages the storing and retrieval of:

  • Meta click ID (fbc)
  • Meta browser ID (fbp)
  • Client IP Address (client_ip_address)

It also provides the normalization and hashing functionality of the following customer information parameters:

  • Email (em)
  • Phone Number (ph)
  • First Name (fn)
  • Last Name (ln)
  • Date of Birth (db)
  • Gender (ge)
  • City (ct)
  • State (st)
  • Zip Code (zp)
  • Country (country)
  • External ID (external_id)

This document describes the parameter builder library from the client-side. The libraries described here are built in JavaScript and will take effect on the client-side.

For information about the server-side library, please refer to the Server-Side Parameter Builder Feature Onboarding Guide. Our recommendation is to implement both the client- and server- side solutions.

Quick-Start Guide / README

Check our github page for README and demo examples: https://github.com/facebook/capi-param-builder/tree/main/client_js

Client-Side Library Overview

clientParamBuilder is the basic library to retrieve and store clickID from URL, cookie and in-app-browser. It helps retrieve client IP addresses from the provided retrieval function. It also provides APIs to retrieve fbc, fbp and client_ip_address. On top of these, it also provides customer information parameters normalization and hashing functionality.

Note: If you are previously using clientParamsHelper v1.1.10 and earlier, please refer to the deprecation guidance here.

Add the Meta Library as a Dependency

clientParamBuilder.js

Add the following script into your webpage.

<script src="https://capi-automation.s3.us-east-2.amazonaws.com/public/client_js/capiParamBuilder/clientParamBuilder.bundle.js"></script>

Manage Cookie Interaction

This section includes some examples to read and store cookies. It’s recommended for advertisers to save the suggested cookies list. Please check the usage below for each API. As for user’s cookie and consent, please refer to Meta’s business tools terms for details.

Integration with cookie consent

Businesses can implement code that creates a banner and requires affirmative consent (for example, an “I agree” checkbox at the top of the page) to allow cookie saving actions through clientParamBuilder. If you already have a system in place that addresses this need, such as a tag manager, you can make this code optional.

clientParamBuilder.js

Client-side clientParamBuilder library will automatically set cookies using the provided API.

<script>       
// optional to input your current Url and getIpFn as clientParamBuilder.processAndCollectAllParams(url, getIpFn);
clientParamBuilder.processAndCollectAllParams(url, getIpFn); 
</script>

Using the API

ClientParamBuilder

The builder library currently supports five APIs:

  • processAndCollectAllParams
  • getNormalizedAndHashedPII
  • getFbc
  • getFbp
  • getClientIpAddress.

Please call processAndCollectAllParams (URL, getIpFn) first before you call getFbc(), getFbp() or getClientIpAddress().

processAndCollectAllParams

processAndCollectAllParams will cover everything in processAndCollectParams. If the fbc does not exist or the URL doesn’t contain fbclid, we’ll try to collect the clickID from window.location.href. If client ip retrieval function (getIpFn) is provided, we will use it to retrieve the client_ip_address for you and save to cookie with key _fbi for later retrieval on advertiser server to send to Meta via CAPI as client_ip_address.

// @params url: [optional] string. The full URL you want to collect clickID from.
// @params getIpFn: [optional] function. The function you implemented to collect client IPv6 addresses from. If IPv6 is not available for clients, you should fallback to IPv4.
// @return will process and save cookies for fbc (if available), fbp and client_ip_address (if available), and return the updated cookie (fbc if available, fbp, client_ip_address if available).
processAndCollectAllParams(url,getIpFn) 

Usage example:
(async() => {

// Async function to fetch the user's IPv6 address,if not available fallback to IPv4 
 const getIpFn = async function () {
   return await (await fetch('https://api64.getIpExample.org')).text();
 };

const updated_cookie = await clientParamBuilder.processAndCollectAllParams("https://mytest.example.com?balabala=test", getIpFn);
const fbc = updated_cookie['_fbc'];
const fbp = updated_cookie['_fbp'];
const client_ip_address = updated_cookie['_fbi'];
})();

Note: clientParamBuilder.processAndCollectAllParams is an async call to save the fbc, fbp and client_ip_address to cookie using key _fbc, _fbp and _fbi respectively. If your use case doesn't require any complex settings, you don't necessarily need its return value. Call getFbc(), getFbp() and getClientIpAddress when you need them.

Note: If you use processAndCollectParams, we mark processAndCollectParams as deprecated. Please use processAndCollectAllParams instead.


getIpFn

getIpFn is a function you can provide as the second parameter (optional) when calling processAndCollectAllParams. getIpFn provides a function to retrieve client IPv6 addresses. We will invoke this function to retrieve client IPv6 addresses and save the return value to cookie as _fbi. The cookie value will be retrieved later on your server before being sent to the Conversions API as client_ip_address.

If your client does not have an IPv6 address, return the IPv4 address of the client instead. The expected return value is a plain text IPv6 or IPv4 string.

// @return clientIpAddress: string, the valid client IPv6 address. If the IPv6 address is not available for the client, then fallback to the valid IPv4 address of the client.
getIpFn()

Example Pseudo Code:


// Async function to fetch the user's IPv6 address,if not available fallback to IPv4 
 const getIpFn = async function () {
   return await (await fetch('https://api64.getIpExampleSite.org')).text();
 };

Example return values:

2001:0db8:85a3:0000:0000:8a2e:0370:7334 or 168.212.226.204


getNormalizedAndHashedPII

This API returns the normalized and hashed (sha256) customer information parameters (PII). If input is invalid, this API will return null. This method takes two parameters. The first parameter is the PII value to normalize and hash. The second parameter is the type of PII you want to normalize as. Available options are: 'phone', 'email', 'first_name', 'last_name', 'date_of_birth', 'gender', 'city', 'state', 'zip_code', 'country' and 'external_id'.

// @params piiValue: string. The customer information parameters(PII) value we want to normalize and hash.
// @params dataType: string. The type of PII you want to normalize as. Available options are: 'phone', 'email', 'first_name', 'last_name', 'date_of_birth', 'gender', 'city', 'state', 'zip_code', 'country' and 'external_id'
// @return NormalizedAndHashedPII: string or null, the normalized and hashed PII. We will return null with invalid input.
getNormalizedAndHashedPII(piiValue,dataType)

Usage example:

getNormalizedAndHashedPII(‘John_Smith@gmail.com’,’email’);
getNormalizedAndHashedPII(‘+1 (616) 954-78 88’,’phone’);

getFbc

The API getFbc returns the fbc value from cookie. This API will return an empty string if the cookie does not exist.

// @return fbc string or empty string if none exists
getFbc();

getFbp

The API getFbp returns the fbp value from cookie. This API will return an empty string if the cookie does not exist.

// @return fbp string or empty string if none exists
getFbp();

getClientIpAddress

The API getClientIpAddress returns the client_ip_address value from cookie. This API will return an empty string if the cookie does not exist.

// @return client_ip_address string or empty string if none exists
getClientIpAddress();

Deprecation of clientParamsHelper

The clientParamsHelper library has been deprecated. All functions within clientParamsHelper should be already moved to clientParamBuilder. Please check on the clientParamBuilder API for the replacement.

See Also