Conversions API

Parameter Builder Library

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.

This document includes an overview of both libraries, guidance on which library to use, and example use cases.

Library Overview

Client-side: The library and events live in the front end on the browser side. The libraries are implemented in JavaScript. Developers may integrate it in their web page directly.

Server-side: The libraries and events live in the back end on the server side. Depending on the language the backend uses, Meta provides libraries in different languages (PHP, Java, Python, NodeJS and Ruby).

Choosing a Library

All libraries can work independently. To maximize the potential for you or your customers, please review the recommendations here.

Parambuilder adheres to the best practices referenced in Meta’s developer documentation. It is implemented on the client-side (JavaScript) and server-side (PHP, Java, Python, NodeJS, Ruby).

Example Use Cases for Reference

The following use cases may be worth considering as you are building the solution.

Recommended: Server-Side Parameter Builder + Client-Side Parameter Builder

Pairing the server-side parameter builder and client-side parameter builder may help maximize your potential to achieve high fbc and IPv6 coverage.

To do so, you’ll need to integrate two libraries together: server-side parameter builder and client-side parameter builder.




Example workflow

  • Advertiser client application loads client-side parameter builder and invokes provided API processAndCollectAllParams with a function pointer getIpFn.
  • The provided getIpFn will be invoked and fetch IPv6 from an advertiser configured endpoint depending on the actual getIpFn implementation.
  • The IPv6 will be returned from the advertiser configured endpoint and passed back to client-side parameter builder from the return value of getIpFn. The retrieved IPv6 will be stored in the cookie with key _fbi for later retrieval.
  • On the client side, start your business as usual communications to the back-end server using the fetch API (or other front-back end communication) with the 1st party cookies.
  • On the server-side, integrate the server-side library based on your choice of language in the receiver endpoint (for example, ExampleController) and invoke the provided API processRequest to handle the request.
  • The processRequest API will return a list of cookies recommended to be updated on the client-side.
  • Set recommended cookies in response headers to instruct client browser to store it.
  • Invoke various provided APIs like getFbc(), getFbp(), getClientIpAddress() and getNormalizedAndHashedPII().
  • SDK returns various values like fbc, fbp, client_ip_address, email and phone number.
  • Send these retrieved values back to Meta through Conversions API.
// Example Controller which processes all requests to example.com
// Start process
ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList('example.com', 'yourDomain.com'));
// Input the request's full URL, such as: example.com?fbclid=xxxxx
// Process and get recommended updated cookie
List<CookieSetting> updatedCookieList =
        paramBuilder.processRequest(
            request.getHeader("host"),  // example.com
            request.getParameterMap(), // {'fbclid':['xxxxx']}
            cookieMap, 
            request.getHeader("referer"),
request.getHeader("X-Forwarded-For"),
request.getRemoteAddr(),
); // optional: referer full url


// Save cookie from server side
for (CookieSetting updatedCookie : updatedCookieList) {
      Cookie cookie = new Cookie(updatedCookie.getName(), updatedCookie.getValue());
      cookie.setMaxAge(updatedCookie.getMaxAge());
      cookie.setDomain(updatedCookie.getDomain());
      response.addCookie(cookie);
 }

// Get fbc, fbp, client_ip_address
String fbc = paramBuilder.getFbc();
String fbp = paramBuilder.getFbp();
String client_ip_address = paramBuilder.getClientIpAddress();

// Get Normalized and Hashed PII like email and phone number
String normalizedAndHashedEmail = paramBuilder.getNormalizedAndHashedPII(‘John_Smith@gmail.com’,’email’);
String normalizedAndHashedPhone = paramBuilder.getNormalizedAndHashedPII(‘(650)555-1212’,’phone’);

// Call CAPI endpoint
.....
.setFbc(fbc)
.setFbp(fbp)
.setClientIpAddress(client_ip_address)
.setEmail(normalizedAndHashedEmail)
.setPhone(normalizedAndHashedPhone)
....

Server-Side ParamBuilder Only

Please review the Server-Side Parameter Builder Onboarding Guide or the README files linked within for some detailed examples.

Example workflow

  • In the server's endpoint, import the ParamBuilder library based on the relevant language and framework.
  • Call paramBuilder.processRequest to get a list of recommended updated cookies.
  • Set cookies to your response.
  • Set fbc, fbp, client_ip_address and other PII such as email and phone number to the Conversions API’s call by using paramBuilder.getFbc(), paramBuilder.getFbp(), paramBuilder.getClientIpAddress() and paramBuilder.getNormalizedAndHashedPII() respectively

Client-Side ParamBuilder Only

Please review the Client-Side Parameter Builder Onboarding Guide or the README files linked within for some detailed examples.

Example workflow

  • When loading the landing page, call clientParamBuilder.processAndCollectAllParams(url, getIpFnl).
  • The request is then sent to the server side. The server can then read fbc, fbp and client_ip_address from the cookie using key _fbc, _fbp and _fbi respectively.
    • Note: If the landing URL doesn’t contain fbclid, fbc might be missing. This is expected behavior.

Useful Links

Main Github link

Please make sure you are on the latest version.

Best Practices

  • Make sure you save the _fbp and _fbc cookies as early as possible in the customer journey in your webpage. Ideally retrieve _fbp and _fbc cookies when loading your landing page. It’s not recommended to retrieve them only from down-funnel events or when certain events are triggered.
  • Do not override or adjust the _fbc or _fbp cookie. _fbc is case sensitive; do not normalize or format the _fbc to lowercase.
  • Make sure the libraries are applied to all surfaces, such as mobile, desktop, and browsers, and domains you want to track.
  • Server-side library is for the back-end side and the client-side library is for the front-end browser side. Developers may integrate the client-side library in their web page directly, while the server-side libraries are called in the back-end server side. Note that client-side is only available in JavaScript while the server-side library provides support for different languages (PHP, Java, Python, NodeJS and Ruby).
  • When you implement the getIpFn functionality, we recommend retrieving the IPv6 address first, then fallback to the IPv4 address if the IPv6 address retrieval capability is not available from the user's client side.
  • We recommend you integrate both client and server parameter builder to achieve optimized performance. You can use the client-side parameter builder to retrieve client_ip_address and save to a cookie. Later on you can use the server-side parameter builder to get the best available client_ip_address from both cookie and request to send to Meta using the Conversions API.
  • We recommend applying normalization and hashing to customer information parameters only once—either on the client side or the server side—before sending them to Meta through the Conversions API.
  • All the customer information parameter fields’ values returned from the parameter builder are case sensitive. You can send these values as is back to Meta through the Conversions API without any normalizing (for example, lowercase), as it has been done automatically by the parambuilder SDK in the process.

See Also