Conversions API

Parameter Builder Workflow and Examples

The parameter builder library is a lightweight SDK designed to fit in the majority of the systems.

Workflow

You can find example demos for each language under their respective sub-directories: A localhost-based demo application is under the folder titled /example. The README file shows how to run the demo application in localhost step by step.

Client-side SDK

Directory:

High-level integration guidance:

  • Load the SDK: clientParamBuilder is loaded during page initialization.
  • Call the SDK APIs: The advertiser’s website calls the APIs provided by clientParamBuilder. For example:
    • .processAndCollectAllParams saves and updates fbp, fpc and fbi (if getIpFn is available)
      • If getIpFn is not empty, fbi will be saved in the cookie, based on the pass-in function getIpFn result.
      • Saves fbc if applicable.
      • Saves fbp if applicable.
    • .getNormalizedAndHashedPII: Return normalized and hashed PII data based on input value and type.
    • .getFbc(), getFbp(), getClientIpAddress(): Call .processAndCollectAllParams first to set in cookies, and retrieve the results from the cookie. Note: this API will save/update cookies. Make sure the website has the user's cookie consent before calling.
  • Send the Conversions API payload: The advertiser’s website sends the Conversions API payload with retrieved parameters.

Refer to full instructions in README file.

Server-side SDK

Directories:

High-level integration guidance:

  • Import param builder library into advertiser’s website server application.
  • Process the request: Call updatedCookieList = builder.processRequest with input data.
  • Get the cookies to set: Either use updatedCookieList or builder.getCookiesToSet to get a list of cookies we recommend saving.
  • Save the cookies: The advertiser's website server saves cookies based on the above list.
  • Fetch the parameters. Retrieve values using:
    • getFbc()
    • getFbp()
    • getClientIpAddress()
    • getNormalizedAndHashedPII()
  • Send the Conversions API payload: The advertiser’s website sends payload with the above parameters.

[Recommended] Client-side + Server-side SDK

You can also integrate both client-side and server-side SDK in the same web application. They are compatible with each other, and leverage cookies for major interactions. This can help maximize the effectiveness of the parameter builder library.

click image to enlarge



  1. Advertiser client application loads client-side parameter builder and invokes provided API processAndCollectAllParams with a function pointer getIpFn.
  2. The provided getIpFn will be invoked and fetch IPv6 from an advertiser-configured endpoint, depending on the actual getIpFn implementation.
  3. 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.
  4. 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 first-party cookies.
  5. 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.
  6. The processRequest API will return a list of cookies we recommend updating on the client-side.
  7. Set the recommended cookies in response headers to instruct the client browser to store them.
  8. Invoke various provided APIs like getFbc(), getFbp(), getClientIpAddress() and getNormalizedAndHashedPII().
  9. The SDK will return various values such as fbc, fbp, client_ip_address, email and phone number.
  10. Send these retrieved values back to Meta through the Conversions API.