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 events’ parameters (for example, fbc and fbp), 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, review the recommendations here.

Broken down by functionality, there are two types of libraries Meta supports:

  • The base library parambuilder
  • The extension library paramshelper

Base libraries: parambuilder

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).

Extension library: paramshelper

Paramshelper, also known as clientParamsHelper, only works on the front-end client side. It is a JavaScript library to retrieve backup clickID from the in-app browser. It may help further increase fbc retrieval and its quality, that is, the number of events that contain fbc as a percentage of the total number of events.

Paramshelper can work independently, but we recommend supplementing it with server side parameter builder SDK to maximize its potential.

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 paramshelper

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

To do so, you’ll need to integrate two libraries together: server-side ParamBuilder and ClientHelper.




Example workflow:

  1. ClientParamsHelper calls await decorateUrl(existing_url) on the client-side when loading the page.
  2. On the client side, the fetch API (or other front-back end communication) calls with the full URL (for example: example.com?fbclid=xxxxx) to the back-end server.
  3. On the server-side, integrate the server library based on your choice of language in the receiver endpoint (for example, ExampleController) 
 // 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")); // 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
String fbc = paramBuilder.getFbc();
String fbp = paramBuilder.getFbp();

// Call CAPI endpoint
.....
.setFbc(fbc)
.setFbp(fbp)
....

Client-side ParamBuilder + ParamsHelper

If you would like to integrate with client-side libraries, you can use parambuilder to cover all features.

Example: Integrate with client-side ParamBuilder(clientParamBuilder) only

We currently support the API processAndCollectAllParams(url) when loading the page. It will adopt both features from clientParamBuilder and clientParamsHelper to retrieve and store fbc and fbp cookies.

Example workflow:

  1. The clientParamBuilder library will be called as processAndCollectAllParams(url) when loading the page.
  2. The request is sent to the server side. The server can then read fbc, fbp from the cookie.

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:

  1. In the server's endpoint, import the ParamBuilder library based on the relevant language and framework.
  2. Call paramBuilder.processRequest to get a list of recommended updated cookies.
  3. Set cookies to your response.
  4. Set fbc and fbp to the Conversions API’s call using paramBuilder.getFbc() and paramBuilder.getFbp().

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:

  1. When loading the landing page, call clientParamBuilder.processAndCollectParams(url).
  2. The request is then sent to the server side. The server can then read fbc and fbp from the cookie.
    • Note: If the landing URL doesn’t contain fbclid, fbc might be missing. This is expected behavior.

Best Practices

  1. 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 down-funnel events or when certain events are triggered.
  2. Do not override or adjust the _fbc or _fbp cookie. _fbc is case sensitive; do not normalize or format the _fbc to lowercase.
  3. Make sure the libraries are applied to all surfaces, such as mobile, desktop, and browsers, and domains you want to track.
  4. Server-side library is for back end side and client-side library is for 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 server, back-end side. Note that client-side is only available in JS while Meta provides libraries in different languages (PHP, Java, Python, NodeJS and Ruby) for the server-side library.

See Also