io.github.adsandcode/fbc-guard

fbc-guard

Static checks for the landing-page code that stores Meta's click ID.

Documentation and background: adsandcode.com/en/open-source/fbc-guard

fbc-guard reads the HTML and JavaScript that turn the fbclid URL parameter into the _fbc cookie (and, if you write it yourself, the _fbp cookie), and flags the known ways that code changes or loses the click ID.

It runs as an MCP server, so an AI assistant can check tracking code while it writes or reviews a page, and as a command-line tool for CI.

The problem it addresses

When someone clicks a Meta ad, the landing page URL carries an fbclid parameter. Your page, or the Meta Pixel, stores it in a first-party _fbc cookie in the form fb.<subdomainIndex>.<creationTime>.<fbclid>, and later events send that value to Meta in the fbc parameter.

Hand-written versions of this code tend to go wrong in a few specific ways:

• They keep an older click ID when a returning visitor arrives from a different ad, so the conversion is attributed to the earlier ad.
• They change the click ID on the way through: decode it again, change its case, or cut it short.
• They write creationTime in seconds instead of milliseconds, or hard-code subdomainIndex.

Advertisers report seeing an Events Manager diagnostic about a modified fbclid in the fbc parameter. Meta's documentation does not list what causes it. The first two mistakes above alter or replace the click ID between the URL and the event, so they are worth ruling out when you see it.

fbc-guard finds these patterns in source code before it ships. It does not run the code and it sends nothing to Meta.

Install

MCP server

Add this to your MCP client configuration (Claude Desktop, Cursor, and other clients that read an mcpServers block):

{
  "mcpServers": {
    "fbc-guard": {
      "command": "npx",
      "args": ["-y", "mcp-server-fbc-guard"]
    }
  }
}

Claude Code:

claude mcp add fbc-guard -- npx -y mcp-server-fbc-guard

Requires Node.js 18 or later.

Command line

npx -y -p mcp-server-fbc-guard fbc-guard https://your-landing-page.example/
# or install it
npm install -g mcp-server-fbc-guard
fbc-guard ./dist/index.html ./dist/js/tracking.js

As a library

import { checkCode } from "mcp-server-fbc-guard";

const result = checkCode(htmlOrJs); // { status, failed, unknown, warnings, rules }

The package entry point is the rules module only. Importing it does not start the MCP server, read files or touch the network.

MCP tools

Both return JSON:

{
  "status": "fail",
  "failed": ["FBC-01"],
  "unknown": [],
  "warnings": ["FBC-06"],
  "rules": [
    {
      "id": "FBC-01",
      "title": "A new fbclid must overwrite an older _fbc cookie",
      "status": "fail",
      "evidence": "indexOf('_fbc=')<0",
      "protects": "If the cookie is only written when it is missing, ...",
      "basis": "official",
      "severity": "error",
      "reference": "https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc"
    }
  ]
}

Each rule's status is pass, fail, unknown or warn. warn comes only from warning-level rules (FBC-06); it is listed under warnings and never changes the overall status or the exit code.

The overall status is pass, fail, unknown, or not_applicable.

• unknown means no rule failed, but at least one rule could not decide. Today only FBC-01 can return it, when it cannot tell which variable holds the fbclid from the URL. The rule's evidence says what could not be resolved.
• not_applicable means the string _fbc does not appear anywhere in what was scanned, so no rule was evaluated. The code may live somewhere the scan cannot see.

Neither is a pass.

In check_fbc_code, kind: "auto" reads the input as HTML when it starts with < and analyses its inline <script> bodies, and reads anything else as JavaScript.

The server runs its own negative tests at startup and refuses to start if any rule no longer fails on the code it is supposed to catch.

Command line

fbc-guard <url|file> [<url|file> ...]   check pages (http/https) or local files
fbc-guard --json <url|file> [...]       print JSON instead of text
fbc-guard --allow-private <url> [...]   also allow localhost and private-network URLs
fbc-guard --selftest                    run only the negative tests
fbc-guard --help | --version

Each target is judged separately. URLs are fetched together with their same-origin scripts. Local files are scanned as they are, without following <script src>, so list your JavaScript files as well. A local file is read as JavaScript when its extension is .js, .mjs, .cjs, .jsx, .ts, .mts, .cts or .tsx, as HTML when it is .html, .htm, .xhtml, .shtml or .php, and otherwise by its first character, as in check_fbc_code.

Before judging any target the CLI runs the same negative tests as the server. If they fail, it prints which test failed and exits with code 2 without giving a verdict.

In CI:

npx -y -p mcp-server-fbc-guard fbc-guard ./public/index.html ./public/js/tracking.js

Rules

Each rule cites Meta's reference page, ClickID and the fbp and fbc Parameters (the older URL under /docs/marketing-api/conversions-api/parameters/fbp-and-fbc/ redirects there). The Basis column says how directly that page supports the rule:

• Official: the page states the requirement.
• Derived: the page states a general requirement; applying it to this specific code pattern is our reading.
• Observed in practice: not stated by Meta; a mistake seen in real implementations.

An error-level rule that fires fails the check (exit code 1). A warning-level rule that fires is reported with status warn and does not change the result or the exit code.

The rules read the source through a small scanner, not a JavaScript parser. Nothing inside a JavaScript comment counts, and neither does markup inside an HTML comment.

• FBC-02, FBC-03 and FBC-04 read only the JavaScript (inline <script> bodies and fetched script files) and also ignore string contents, so a message such as 'do not call decodeURIComponent(fbclid)' does not trigger them.
• FBC-06 and the write-only-if-missing check of FBC-01 look for text that lives inside string literals, so they read the whole document with comments removed and string contents kept.
• FBC-01, FBC-05 and FBP-01 also use the scanner to find where a statement starts and ends.

FBC-01: a new fbclid must overwrite an older _fbc cookie

Code written as "set the cookie if there is none" keeps the first click ID forever. A visitor who returns through a different ad still carries the old one, and the conversion is credited to the earlier ad. Meta's page lists, as a case where the cookie should be set, a URL fbclid that "isn't equal to the corresponding value in the _fbc cookie value".

How the rule decides:

1. It finds the variables that hold the click ID from the URL: assigned from .get('fbclid'), ['fbclid'] or .fbclid, from a match, split, exec or similar call on text containing fbclid=, or copied from one of those (var f = fbclid || ''). A variable or parameter literally named fbclid also counts.
2. It looks for a !==, !=, === or == comparison between one of those variables and something that is not a literal. id !== f and if (stored === clickId) return; count; f !== '' and f != null do not.
3. A comparison passes the rule. That includes "set the cookie if it is missing or different", written as indexOf('_fbc=') < 0 || id !== f.
4. Without a comparison, the rule fails if it finds the write-only-if-missing pattern indexOf('_fbc=') < 0, or if it found a click ID variable.
5. If it found neither a click ID variable nor that pattern, the status is unknown, with an explanation. Exit code 0.

FBC-02: do not URL-decode fbclid a second time

URLSearchParams.get() already returns a decoded value. Decoding it again either leaves it unchanged or changes it, and decodeURIComponent throws on a lone %, which stops the rest of the script. Meta's page says to "do not apply any modifications before using" the click ID. It does not mention decoding specifically; treating a second decode as a modification is our reading.

FBC-03: do not change the case of fbclid

Meta's page states "ClickID value is case sensitive" and names lower- and upper-casing as modifications to avoid.

FBC-04: do not truncate fbclid

A shortened click ID is a modified click ID. Meta's page says to "do not apply any modifications before using" it; truncation is not named specifically.

FBC-05: _fbc creationTime must be in milliseconds

Meta's page defines it: "creationTime is the UNIX time since epoch in milliseconds". Date.now() already returns milliseconds; dividing by 1000 writes seconds.

The rule looks at each statement that contains an _fbc=fb. string or template literal and fails if that statement divides a millisecond clock by 1000:

• clocks: Date.now(), new Date(), (new Date), new Date().getTime(), (new Date).getTime(), new Date().valueOf(), +new Date, and d.getTime() / d.valueOf() on a variable (a new Date(...) built from arguments is a fixed moment, not the clock, and is not matched);
• divisors: /1000 or /1e3, with or without spaces, whatever wraps it (Math.floor, Math.round, Math.trunc, parseInt, |0, ~~);
• written directly in the concatenation or template literal, or stored in a variable first and concatenated in. For a variable, the last assignment before the statement is the one that counts.

It does not fire on Date.now() alone, on /1000 in other statements (a countdown timer elsewhere in the file), on a commented-out line, or on a time difference such as (end - Date.now()) / 1000, which is a duration like max-age, not a timestamp.

FBC-06 (warning): check a hard-coded subdomainIndex in the _fbc cookie

Meta's page says "subdomainIndex is which domain the cookie is defined on", with com as 0, example.com as 1 and www.example.com as 2. A literal digit is only correct while the cookie is always set on a domain of that level. The page also says to use 1 when the value is generated on a server without saving a cookie, its own examples use fb.1., and it does not say a mismatched value is rejected. So a literal is not wrong in itself, and this rule is a warning, not a failure: it points at a value worth checking against the domain the cookie is actually set on.

FBP-01: _fbp creationTime must be in milliseconds

The fbp section of the same page uses the same definition: "creationTime is the UNIX time since epoch in milliseconds". This only matters if your own code writes _fbp; normally the Meta Pixel does. Detection works as in FBC-05, on statements containing _fbp=fb..

Code that passes every rule

This is the exact snippet the self-test runs through every rule, and the publish check refuses to release a README in which it differs.

<script>
(function () {
  // URLSearchParams.get() already returns the decoded value. Use it as is.
  var fbclid = new URLSearchParams(location.search).get('fbclid');
  if (!fbclid) return;

  // The click ID in an existing _fbc cookie is its fourth field:
  // fb.<subdomainIndex>.<creationTime>.<fbclid>
  var current = (document.cookie.match(/(?:^|;\s*)_fbc=([^;]*)/) || [])[1] || '';
  var storedId = current ? current.split('.')[3] : '';

  // A different click replaces the stored one. The same click keeps it.
  if (storedId !== fbclid) {
    // Use the widest domain the browser accepts for a cookie, and derive
    // subdomainIndex from it: example.com is 1, www.example.com is 2.
    var host = location.hostname, parts = host.split('.');
    var domain = host, domainAttr = '';
    for (var i = parts.length - 2; i >= 0; i--) {
      var candidate = parts.slice(i).join('.');
      document.cookie = 'cookie_domain_probe=1;path=/;domain=' + candidate;
      if (document.cookie.indexOf('cookie_domain_probe=1') >= 0) {
        document.cookie = 'cookie_domain_probe=;path=/;domain=' + candidate + ';max-age=0';
        domain = candidate;
        domainAttr = ';domain=' + candidate;
        break;
      }
    }
    var subdomainIndex = domain.split('.').length - 1;

    // creationTime is Date.now(): milliseconds, not seconds. 90 days = 7776000 s.
    document.cookie = '_fbc=fb.' + subdomainIndex + '.' + Date.now() + '.' + fbclid +
      ';path=/' + domainAttr + ';max-age=7776000;SameSite=Lax';
  }
})();
</script>

Notes on the example:

• Which part of the cookie is the click ID. The example takes the fourth dot-separated segment. Meta's fbc page instead says the click ID is the part of the cookie value after the last dot. The two differ when Meta's Parameter Builder library wrote the cookie: its documented format is fb.${subdomain_index}.${creation_time}.${fbclid}.${appendix}, so the part after the last dot is the appendix, not the click ID. The fourth segment is the click ID in both formats.
• Browsers refuse cookies on public suffixes such as com or com.tw, so the loop settles on the registrable domain (example.com, example.com.tw).
• Prefer a server-set cookie. Meta's fbc page recommends setting _fbc as an HTTP cookie in the response headers, with a 90-day expiration, when the request arrives with fbclid. The example writes it with document.cookie, which is what you can do from a static page, and browsers limit that: WebKit's Intelligent Tracking Prevention 2.2 says "persistent cookies set through document.cookie are capped to one day of storage" when a domain it classifies as a cross-site tracker sent the visitor and the landing URL has a query string or fragment. An ad click always carries fbclid in the query string, so whenever ITP has classified the referring site that way, the 90 days written by this script become one day in Safari. If you control the server, set the cookie there.
• If the Meta Pixel is installed it manages _fbc and _fbp itself. Code like this is for pages that capture the click ID without the Pixel, for example to forward it through the Conversions API.

Changes from the original rule set

This package started as an in-house script with the same rule IDs. For the public release, several rules were reworked because they missed real mistakes or flagged correct code.

• FBC-05 and FBP-01 used to catch Date.now()/1000 only inside the same string or template literal as _fbc=fb. / _fbp=fb.. The common concatenated form '_fbc=fb.' + i + '.' + Math.floor(Date.now()/1000) passed. They now check the whole statement and seconds stored in a variable, as described above, and ignore comments.
• FBC-01 used to accept only !== or != next to a variable literally named fbclid, so correct code such as if (id !== f) or if (stored === fbclid) return; failed. It now resolves which variable holds the click ID, accepts all four comparison operators, and reports unknown instead of failing when it cannot resolve the variable.
• FBC-06 used to fail. Because Meta itself uses fb.1. in its examples and for server-generated values, it is now a warning that does not change the exit code.
• FBC-02, FBC-03, FBC-04 and FBC-06 used to match anywhere in the text, including comments, so a comment that warned against a mistake triggered the rule. They now skip comments, and FBC-02 to FBC-04 also skip string contents.

On the original test fixtures every rule gives the same result as before, except that FBC-06 now reports warn where it used to report fail.

Limitations

This is static analysis of source text, not execution. Read a pass as "none of the known mistakes were found in the shapes this tool recognises", not as "this code is correct".

• False negatives. Minified, bundled or obfuscated code and code assembled at runtime can hide a mistake. FBC-02, FBC-03 and FBC-04 only look at a variable literally named fbclid, so f.toLowerCase() is not caught. FBC-05 and FBP-01 need the _fbc=fb. / _fbp=fb. text in one string or template literal; a value assembled as '_fbc=' + value or with join('.') is not checked, and seconds returned from a helper function are not traced. Variable tracking is textual: it takes the last assignment before the statement and does not follow scopes or branches.
• False positives. FBC-01 accepts any comparison between the click ID and a non-literal, so it cannot tell whether the other side really is the stored cookie value. That makes a false pass more likely than a false failure. A seconds variable that is reassigned inside a branch can be judged by the wrong assignment.
• HTML or JavaScript. Inline event handler attributes (onclick="...") are not analysed by FBC-01 to FBC-05 or FBP-01. A JavaScript file that starts with < is read as HTML unless you pass kind: "js" or give it a .js extension.
• Not applicable is not a pass. If _fbc does not appear in what was scanned, nothing is judged. Tracking code in a tag manager container, a cross-origin script, or a server-side integration is invisible to this scan.
• URL scanning limits. Only same-origin scripts are fetched, at most 20, up to 2 MB each after decompression, with a 30-second timeout per request, at most 5 redirects, and a mobile Safari user agent. Cross-origin scripts are never fetched; they are listed under skipped_scripts. A same-origin script that redirects to another origin is not followed. Markup served only after JavaScript runs is not seen. Proxy environment variables are not used.
• No runtime check. Static analysis cannot tell you what value is actually sent. To confirm, load the page in a browser with an old _fbc cookie already set and a realistic fbclid in the URL, and compare what your code sends with the URL value character by character. Block requests to Meta while testing so test click IDs are not reported as real events.

Network safety

check_fbc_url and the CLI's URL mode fetch whatever URL they are given, and an AI agent may be the one choosing it. To keep that from becoming a way into cloud metadata endpoints, localhost services or a private network, fetching is limited to public hosts by default:

• Only http and https URLs are accepted.
• A connection is refused when the host is, or resolves to, a loopback, private (10/8, 172.16/12, 192.168/16, fc00::/7), link-local (169.254/16, fe80::/10), carrier-grade NAT (100.64/10), 0.0.0.0/8, multicast, reserved or unspecified address, including those addresses written inside IPv6 (::ffff:127.0.0.1, NAT64, 6to4). If any address a name resolves to is refused, the name is refused.
• Redirects are followed by hand, at most 5, and every hop is checked the same way, as is every same-origin script.
• A refused address, a DNS failure, a refused or reset connection, a TLS error and a timeout all return the same error text, so the tool cannot be used to tell open ports from closed ones by its messages.

To check a page on your own machine or intranet, opt in: --allow-private on the command line, or FBC_GUARD_ALLOW_PRIVATE=1 in the MCP server's environment:

{
  "mcpServers": {
    "fbc-guard": {
      "command": "npx",
      "args": ["-y", "mcp-server-fbc-guard"],
      "env": { "FBC_GUARD_ALLOW_PRIVATE": "1" }
    }
  }
}

With the opt-in, no address is refused.

Residual risks:

• DNS rebinding. A hostname can resolve to a public address when checked and a private one when connected. The address check runs inside the connection's own DNS lookup, on the addresses the socket is about to use, and every redirect hop and script is resolved and checked again, so a changing answer cannot slip between a check and a connection. This depends on Node.js calling that lookup for every connection, which it does for host names; IP literals are checked before connecting. Treat it as a mitigation, not a guarantee.
• Timing. A refused address fails at once, while an unreachable public host may take up to the 30-second timeout, so timing still reveals something even though the messages do not.
• Public hosts that reach inward. A public URL whose own server fetches an internal resource on your behalf (an open proxy, for example) is outside what an address check can see.

Development

npm ci
npm run build
npm run selftest                     # negative tests: every rule must fail on its own fixture
node scripts/smoke.mjs               # talks to the built server over stdio, including a local HTTP check
node scripts/check-publish-ready.mjs # package and MCP Registry metadata checks

License

MIT. See LICENSE.

Maintainer

Built and maintained by Ads & Code.