{"_id":"meta-capi-param-builder-clientjs","_rev":"6-fe2f5cda262d8224a6635aad5eca0c0e","name":"meta-capi-param-builder-clientjs","dist-tags":{"latest":"1.3.2"},"versions":{"1.2.2":{"name":"meta-capi-param-builder-clientjs","version":"1.2.2","author":{"name":"Facebook"},"license":"SEE LICENSE IN LICENSE","_id":"meta-capi-param-builder-clientjs@1.2.2","maintainers":[{"name":"ppwang-sa","email":"ppwang@meta.com"}],"homepage":"https://github.com/facebook/capi-param-builder#readme","bugs":{"url":"https://github.com/facebook/capi-param-builder/issues"},"dist":{"shasum":"3e1631617851741834daa7d566780fb32253abc8","tarball":"https://registry.npmjs.org/meta-capi-param-builder-clientjs/-/meta-capi-param-builder-clientjs-1.2.2.tgz","fileCount":45,"integrity":"sha512-/iHZNphlJGMJAT/1dodUbkGCFIWh/yU/Kw6LxUrYECWo9iU46zeigPsCvUJW0Ai701um5dvBkxIthgqMAxhZNA==","signatures":[{"sig":"MEQCIHGy9IIW8VpQuBNZ6RQQDAhJQxASqU4DLypeOHUt0T/aAiA0f1AAWXUO55Wac6t2IuVm85LUClBxm39FCvlVpcQylA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":387174},"jest":{"transform":{"^.+\\.js$":"babel-jest"},"testEnvironment":"jsdom","moduleNameMapper":{"^@shared(.*)$":"<rootDir>/shared$1"}},"main":"dist/clientParamBuilder.bundle.js","engines":{"node":">=18"},"gitHead":"3b0fcce7e928a0381706cd1d213426b647075fee","scripts":{"lint":"eslint --fix .","test":"jest","build":"webpack --mode production","format":"prettier --write .","version":"echo $npm_package_version","build:dev":"webpack --mode development","clear_jest":"jest --clearCache","prepublishOnly":"yarn test && yarn build","build:dev:example":"yarn run build:dev && cp dist/*js example/public/dev/ && cd example && node server.js"},"_npmUser":{"name":"ppwang-sa","email":"ppwang@meta.com"},"overrides":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"repository":{"url":"git+https://github.com/facebook/capi-param-builder.git","type":"git","directory":"client_js"},"_npmVersion":"11.9.0","description":"Conversions API parameter builder for Client-side JavaScript","directories":{},"resolutions":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"_nodeVersion":"25.6.1","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.27.0","globals":"^15.8.0","webpack":"^5.97.1","prettier":"^3.5.1","@eslint/js":"^8.27.0","babel-jest":"^29.7.0","@babel/core":"^7.26.8","webpack-cli":"^5.1.4","babel-loader":"^9.2.1","core-js-pure":"3.32.2","@babel/preset-env":"^7.26.8","eslint-config-prettier":"^8.10.0","eslint-plugin-prettier":"^5.2.1","jest-environment-jsdom":"^29.7.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-capi-param-builder-clientjs_1.2.2_1774399061245_0.3482839245862053","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"meta-capi-param-builder-clientjs","version":"1.3.0","author":{"name":"Facebook"},"license":"SEE LICENSE IN LICENSE","_id":"meta-capi-param-builder-clientjs@1.3.0","maintainers":[{"name":"fb","email":"opensource+npm@fb.com"},{"name":"ppwang-sa","email":"ppwang@meta.com"}],"homepage":"https://github.com/facebook/capi-param-builder#readme","bugs":{"url":"https://github.com/facebook/capi-param-builder/issues"},"dist":{"shasum":"76f40dcf6fc7060482e6f180872ea7be760e49fb","tarball":"https://registry.npmjs.org/meta-capi-param-builder-clientjs/-/meta-capi-param-builder-clientjs-1.3.0.tgz","fileCount":45,"integrity":"sha512-Bx/PE8htzljopHRXRZN1gXBp2/bHspA9m2ysTyLWd6Jcr81pZsGgEYQWCI+suhpmjfNd4aQkUt2B/2k+lZ3jvg==","signatures":[{"sig":"MEQCIFl2ktw1LBtMpjEFP0tAQDxqotNlc2x/STslBfU7sqk/AiAgBQn2dfHzdMeNwuoM0+kCfTnrCJvKdT9eqfrmxTxVzQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":388234},"jest":{"transform":{"^.+\\.js$":"babel-jest"},"testEnvironment":"jsdom","moduleNameMapper":{"^@shared(.*)$":"<rootDir>/shared$1"}},"main":"dist/clientParamBuilder.bundle.js","engines":{"node":">=20"},"gitHead":"9278bf825b9d053716857d6e11efd75e58ffefb2","scripts":{"lint":"eslint --fix .","test":"jest","build":"webpack --mode production","format":"prettier --write .","version":"echo $npm_package_version","build:dev":"webpack --mode development","clear_jest":"jest --clearCache","prepublishOnly":"yarn test && yarn build","build:dev:example":"yarn run build:dev && cp dist/*js example/public/dev/ && cd example && node server.js"},"_npmUser":{"name":"ppwang-sa","email":"ppwang@meta.com"},"overrides":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"repository":{"url":"git+https://github.com/facebook/capi-param-builder.git","type":"git","directory":"client_js"},"_npmVersion":"10.9.7","description":"Conversions API parameter builder for Client-side JavaScript","directories":{},"resolutions":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.27.0","globals":"^15.8.0","webpack":"^5.97.1","prettier":"^3.5.1","@eslint/js":"^8.27.0","babel-jest":"^29.7.0","@babel/core":"^7.26.8","webpack-cli":"^5.1.4","babel-loader":"^9.2.1","core-js-pure":"3.32.2","@babel/preset-env":"^7.26.8","eslint-config-prettier":"^8.10.0","eslint-plugin-prettier":"^5.2.1","jest-environment-jsdom":"^29.7.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-capi-param-builder-clientjs_1.3.0_1775621414582_0.8614363608874249","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"meta-capi-param-builder-clientjs","version":"1.3.1","author":{"name":"Facebook"},"license":"SEE LICENSE IN LICENSE","_id":"meta-capi-param-builder-clientjs@1.3.1","maintainers":[{"name":"fb","email":"opensource+npm@fb.com"},{"name":"ppwang-sa","email":"ppwang@meta.com"},{"name":"xuanjie","email":"xuanjie@meta.com"}],"homepage":"https://github.com/facebook/capi-param-builder#readme","bugs":{"url":"https://github.com/facebook/capi-param-builder/issues"},"dist":{"shasum":"94ab8e1bbffc7f0befa9ef4ea54d01c71c9c61b0","tarball":"https://registry.npmjs.org/meta-capi-param-builder-clientjs/-/meta-capi-param-builder-clientjs-1.3.1.tgz","fileCount":45,"integrity":"sha512-9KfOeZKvj5QF0Z+BP5mwuAswQh8iFfHXPCTauIukxE0wFkB48lD9nDM1rjK5iklQeRwD7J7HCDxg48KPOMIcaw==","signatures":[{"sig":"MEUCIQDwMN3sANmjKYhfK/lYYD+DmOObZAbnxIs/aCS7WImK/QIgKThuNGZnxkbGyHpow/eKrTSnApdXPYrGK71XVhAaUUg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":389148},"jest":{"transform":{"^.+\\.js$":"babel-jest"},"testEnvironment":"jsdom","moduleNameMapper":{"^@shared(.*)$":"<rootDir>/shared$1"}},"main":"dist/clientParamBuilder.bundle.js","engines":{"node":">=20"},"gitHead":"f334b269b70b50ebd6ae040419aef1e24bbf8957","scripts":{"lint":"eslint --fix .","test":"jest","build":"webpack --mode production","format":"prettier --write .","version":"echo $npm_package_version","build:dev":"webpack --mode development","clear_jest":"jest --clearCache","prepublishOnly":"yarn test && yarn build","build:dev:example":"yarn run build:dev && cp dist/*js example/public/dev/ && cd example && node server.js"},"_npmUser":{"name":"ppwang-sa","email":"ppwang@meta.com"},"overrides":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"repository":{"url":"git+https://github.com/facebook/capi-param-builder.git","type":"git","directory":"client_js"},"_npmVersion":"11.9.0","description":"Conversions API parameter builder for Client-side JavaScript","directories":{},"resolutions":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"_nodeVersion":"25.6.1","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.27.0","globals":"^15.8.0","webpack":"^5.97.1","prettier":"^3.5.1","@eslint/js":"^8.27.0","babel-jest":"^29.7.0","@babel/core":"^7.26.8","webpack-cli":"^5.1.4","babel-loader":"^9.2.1","core-js-pure":"3.32.2","@babel/preset-env":"^7.26.8","eslint-config-prettier":"^8.10.0","eslint-plugin-prettier":"^5.2.1","jest-environment-jsdom":"^29.7.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-capi-param-builder-clientjs_1.3.1_1781540446397_0.08139428714293628","host":"s3://npm-registry-packages-npm-production"}},"1.3.2":{"_id":"meta-capi-param-builder-clientjs@1.3.2","bugs":{"url":"https://github.com/facebook/capi-param-builder/issues"},"dist":{"shasum":"6b163cfba42e64a50467b7f43ca11c757936f1e1","tarball":"https://registry.npmjs.org/meta-capi-param-builder-clientjs/-/meta-capi-param-builder-clientjs-1.3.2.tgz","fileCount":45,"integrity":"sha512-dvGEUETT4gvvjdrk8TN6yOGecHSwsEpXWFobGHl689gbfiRN+hp3k661uO//hVNrQ02Z2HdNtYAmyOmLHVvRbw==","signatures":[{"sig":"MEYCIQDk7CXzrhoPfgkfTJwsWmyIn5dETi63w1Sn3jiYBdNJGwIhAMaoVoSDhwM7YSZMpbLHMRDWe/qhA0QC/vKwL3KmEhq5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEMCIFGE8Pm+/RnW6ASZGRptxR2bWu7MFH5oWYwvPCuqRLkjAh8dRDWX7AnxQhAgNNcNHNQaa/aO2+d9jkNK5MCQFNbx"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/meta-capi-param-builder-clientjs@1.3.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":394213},"jest":{"transform":{"^.+\\.js$":"babel-jest"},"testEnvironment":"jsdom","moduleNameMapper":{"^@shared(.*)$":"<rootDir>/shared$1"}},"main":"dist/clientParamBuilder.bundle.js","name":"meta-capi-param-builder-clientjs","author":{"name":"Facebook"},"engines":{"node":">=20"},"gitHead":"8b3a8f92962ad8ec47b854056643fa335039fa4d","license":"SEE LICENSE IN LICENSE","scripts":{"lint":"eslint --fix .","test":"jest","build":"webpack --mode production","format":"prettier --write .","version":"echo $npm_package_version","build:dev":"webpack --mode development","clear_jest":"jest --clearCache","prepublishOnly":"yarn test && yarn build","build:dev:example":"yarn run build:dev && cp dist/*js example/public/dev/ && cd example && node server.js"},"version":"1.3.2","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:de6d4254-6612-47ae-921c-8dc90ce51de2"}},"homepage":"https://github.com/facebook/capi-param-builder#readme","overrides":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"repository":{"url":"git+https://github.com/facebook/capi-param-builder.git","type":"git","directory":"client_js"},"_npmVersion":"11.19.1","description":"Conversions API parameter builder for Client-side JavaScript","directories":{},"maintainers":[{"name":"fb","email":"opensource+npm@fb.com"},{"name":"ppwang-sa","email":"ppwang@meta.com"},{"name":"xuanjie","email":"xuanjie@meta.com"}],"resolutions":{"@tootallnate/once":"^3.0.1","serialize-javascript":"^7.0.3"},"_nodeVersion":"22.23.2","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.27.0","globals":"^15.8.0","webpack":"^5.97.1","prettier":"^3.5.1","@eslint/js":"^8.27.0","babel-jest":"^29.7.0","@babel/core":"^7.26.8","webpack-cli":"^5.1.4","babel-loader":"^9.2.1","core-js-pure":"3.32.2","@babel/preset-env":"^7.26.8","eslint-config-prettier":"^8.10.0","eslint-plugin-prettier":"^5.2.1","jest-environment-jsdom":"^29.7.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/meta-capi-param-builder-clientjs_1.3.2_1789632810482_0.9979402570709015"}}},"time":{"created":"2026-03-25T00:37:41.161Z","modified":"2026-09-17T08:13:30.931Z","1.2.2":"2026-03-25T00:37:41.384Z","1.3.0":"2026-04-08T04:10:14.801Z","1.3.1":"2026-06-15T16:20:46.566Z","1.3.2":"2026-09-17T08:13:30.581Z"},"bugs":{"url":"https://github.com/facebook/capi-param-builder/issues"},"author":{"name":"Facebook"},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/facebook/capi-param-builder#readme","repository":{"url":"git+https://github.com/facebook/capi-param-builder.git","type":"git","directory":"client_js"},"description":"Conversions API parameter builder for Client-side JavaScript","maintainers":[{"name":"fb","email":"opensource+npm@fb.com"},{"name":"ppwang-sa","email":"ppwang@meta.com"},{"name":"xuanjie","email":"xuanjie@meta.com"}],"readme":"# Conversions API parameter builder feature for Client-side JavaScript\n\n[![npm](https://img.shields.io/npm/v/meta-capi-param-builder-clientjs)](https://www.npmjs.com/package/meta-capi-param-builder-clientjs)\n[![License](https://img.shields.io/badge/license-Facebook%20Platform-blue.svg?style=flat-square)](https://github.com/facebook/capi-param-builder/blob/main/client_js/LICENSE)\n\n## Introduction\n\nThe 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.\n\n[Client-Side Parameter Builder Onboarding Guide](https://developers.facebook.com/docs/marketing-api/conversions-api/parameter-builder-feature-library/client-side-onboarding).\n\n## Quick Start\n\n### Installation\n\nInstall the package via yarn:\n\n```bash\nyarn add meta-capi-param-builder-clientjs\n```\n\nAlternatively, include the bundle directly via a script tag:\n\n```html\n<script src=\"https://unpkg.com/meta-capi-param-builder-clientjs@1.3.2/dist/clientParamBuilder.bundle.js\"></script>\n```\n\nCheck the latest update from [CHANGELOG](./CHANGELOG.md).\n\n### Demo\n\n1. Check the updated version from CHANGELOG.\n2. Checkout the demo example from `./example`. The `example/public/index.html` is the demo on how to use the library.\n\nRun `node server.js` in the example directory, then visit http://localhost:3000. Check console log or cookies to see `_fbp` first.\n\nType the URL http://localhost:3000/?fbclid=test123 — you'll see `fbc` returned in the console log, and the `_fbc` cookie is stored.\n\n## API Usage\n\n### processAndCollectAllParams(url, getIpFn)\n\nProcesses and collects `fbc` and `fbp` parameters (saving them into cookies), and also retrieves client IP addresses. If no `fbc` cookie exists after checking the supplied URL, `window.location.href`, and `document.referrer`, it attempts to retrieve a backup click ID through Extended Browser Properties in supported Facebook and Instagram in-app browsers.\n\n```javascript\nconst params = await clientParamBuilder.processAndCollectAllParams(url, getIpFn);\nconst fbc = params['_fbc'];\nconst fbp = params['_fbp'];\nconst clientIpAddress = params['_fbi'];\n```\n\n> **Important:** Call and await `processAndCollectAllParams()` once per collection flow, then use its returned object for immediate access to the collected values. Do not call it repeatedly just to retrieve individual values because each call reruns collection and invokes `getIpFn` when provided. While the call is still running, `getFbc()` and `getClientIpAddress()` can return an empty or stale cookie value instead of throwing. `getFbp()` is available immediately because the `_fbp` cookie is written before the first asynchronous operation.\n\n- `url` is optional.\n- `getIpFn` is optional — a user-provided function to retrieve client IP addresses. Prefer IPv6 (more precise than IPv4); fall back to IPv4 if IPv6 is not available.\n- Returns an object with `_fbc`, `_fbp`, and `_fbi`.\n\n#### `getIpFn`\n\n- **Input:** none.\n- **Output:** `string | Promise<string>` — the client's **IPv6 address**, with a fallback to **IPv4** if IPv6 is unavailable.\n\n```javascript\nconst getIpFn = async () =>\n  (await fetch('https://api64.ipify.org')).text();\n\nconst params = await clientParamBuilder.processAndCollectAllParams(null, getIpFn);\nconst clientIpAddress = params['_fbi'];\n```\n\n> **Note:** The implementation above is for **demo purposes only**. You should implement your own logic to collect client IPv6 addresses.\n\nThe getters below synchronously read the current cookie values. Use them for later reads when the object returned by `processAndCollectAllParams()` is no longer available.\n\n### getFbc()\n\nReturns the `fbc` value from cookie.\n\n```javascript\nconst fbc = clientParamBuilder.getFbc();\n```\n\n### getFbp()\n\nReturns the `fbp` value from cookie.\n\n```javascript\nconst fbp = clientParamBuilder.getFbp();\n```\n\n### getClientIpAddress()\n\nReturns the `client_ip_address` value from cookie. If no existing `_fbi` cookie is available and an earlier call to `processAndCollectAllParams()` did not use a valid `getIpFn`, this getter returns an empty string.\n\n```javascript\nconst ip = clientParamBuilder.getClientIpAddress();\n```\n\n### getNormalizedAndHashedPII(piiValue, dataType)\n\nReturns normalized and hashed (SHA-256) PII from the input value.\n\n```javascript\nconst hashedEmail = clientParamBuilder.getNormalizedAndHashedPII('user@example.com', 'email');\nconst hashedPhone = clientParamBuilder.getNormalizedAndHashedPII('+1 (616) 954-7888', 'phone');\n```\n\nSupported `dataType` values: `phone`, `email`, `first_name`, `last_name`, `date_of_birth`, `gender`, `city`, `state`, `zip_code`, `country`, `external_id`.\n\n### processAndCollectParams(url) *(Deprecated)*\n\n> **Deprecated:** Use `processAndCollectAllParams` instead. This method is kept for backward compatibility only.\n\n## Development\n\n### Prerequisites\n\n- Node.js >= 20\n- yarn (install via `corepack enable` or see [yarnpkg.com](https://yarnpkg.com/getting-started/install))\n\n### Setup\n\n```bash\ncd client_js\nyarn install\n```\n\n### Build\n\n```bash\nyarn build          # production build\nyarn build:dev      # development build\n```\n\n### Test\n\n```bash\nyarn test                                          # run all tests\nyarn test -- --testPathPattern cookieUtil.test.js   # run specific test file\n```\n\n### Lint and Format\n\n```bash\nyarn lint\nyarn format\n```\n\n## License\n\nThe Conversions API parameter builder feature for Client-side JavaScript is licensed under the [LICENSE](./LICENSE) file in the root directory of this source tree.\n","readmeFilename":"README.md"}