Conversions API parameter builder feature for Client-side JavaScript

Introduction

The Conversions API parameter builder SDK is a lightweight client-side JavaScript tool for improving Conversions API parameter retrieval and quality. It helps advertisers and partners improve match key quality and coverage (especially fbc and fbp) in CAPI events.

Client-Side Parameter Builder Onboarding Guide.

Quick Start

Installation

Install the package via npm or yarn:

npm install meta-capi-param-builder-clientjs

or

yarn add meta-capi-param-builder-clientjs

Alternatively, include the bundle directly via a script tag:

<script src="https://unpkg.com/meta-capi-param-builder-clientjs/dist/clientParamBuilder.bundle.js"></script>

Check the latest update from CHANGELOG.

Demo

1. Check the updated version from CHANGELOG.
2. Checkout the demo example from ./example. The example/public/index.html is the demo on how to use the library.

Run node server.js in the example directory, then visit http://localhost:3000. Check console log or cookies to see _fbp first.

Type the URL http://localhost:3000/?fbclid=test123 — you'll see fbc returned in the console log, and the _fbc cookie is stored.

API Usage

processAndCollectParams(url)

Processes and collects fbc and fbp parameters, saving them into cookies.

const params = clientParamBuilder.processAndCollectParams(url);

• url is optional. Returns an object with _fbc and _fbp values.

processAndCollectAllParams(url, getIpFn)

Extended version that also retrieves client IP addresses and backup click IDs from in-app browsers.

const params = await clientParamBuilder.processAndCollectAllParams(url, getIpFn);

• url is optional.
• getIpFn is optional — a user-provided function to retrieve client IP addresses.

getFbc()

Returns the fbc value from cookie. Call processAndCollectParams first.

const fbc = clientParamBuilder.getFbc();

getFbp()

Returns the fbp value from cookie. Call processAndCollectParams first.

const fbp = clientParamBuilder.getFbp();

getClientIpAddress()

Returns the client_ip_address value from cookie. Call processAndCollectAllParams with a valid getIpFn first, otherwise returns an empty string.

const ip = clientParamBuilder.getClientIpAddress();

getNormalizedAndHashedPII(piiValue, dataType)

Returns normalized and hashed (SHA-256) PII from the input value.

const hashedEmail = clientParamBuilder.getNormalizedAndHashedPII('[email protected]', 'email');
const hashedPhone = clientParamBuilder.getNormalizedAndHashedPII('+1 (616) 954-7888', 'phone');

Supported dataType values: phone, email, first_name, last_name, date_of_birth, gender, city, state, zip_code, country, external_id.

Development

Prerequisites

• Node.js >= 18
• yarn (npm install --global yarn)

Setup

cd client_js
yarn install

Build

yarn build          # production build
yarn build:dev      # development build

Test

yarn test                                          # run all tests
yarn test -- --testPathPattern cookieUtil.test.js   # run specific test file

Lint and Format

yarn lint
yarn format

License

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