Add Meta Pixel analytics provider support by BC-AdamWard · Pull Request #2727 · bigcommerce/catalyst

BC-AdamWard · 2025-11-19T04:43:00Z

What/Why?

Add Meta Pixel (Facebook Pixel) analytics provider to Catalyst analytics framework. Implements standard e-commerce event tracking (ViewContent, AddToCart, RemoveFromCart, ViewCart, ViewCategory) with consent management support. Enables merchants to track events using Meta Pixel alongside or instead of Google Analytics.

Add MetaPixelProvider class implementing AnalyticsProvider interface
Update WebAnalyticsFragment to include metaPixel configuration
Update AnalyticsProvider component to support multiple providers
Add consent management integration for GDPR/CCPA compliance

Testing

Add Meta Pixel to store settings or inline in the Catalyst component.
Load storefront and validate pixel fires against meta pixel

Migration

Minor change

changeset-bot · 2025-11-19T04:43:04Z

🦋 Changeset detected

Latest commit: f6092e4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-11-19T04:43:05Z

@BC-AdamWard is attempting to deploy a commit to the BigCommerce Platform Team on Vercel.

A member of the Team first needs to authorize it.

chanceaclark

Love how simple this add was! Wonder who set this up to be easy... 😏

Have a few comments specific to the provider + some type stuff otherwise looking good.

chanceaclark · 2025-11-19T16:50:54Z

+  getConsent?: () => Analytics.Consent.ConsentValues | null;
+  debugMode?: boolean;


These two properties are based on how the analytics providers manages consent and if it has a debug option.

For the consent piece, do you know if MP handles managing consent on it's own, like GA does? Or does it always assume you have consent when placed on the page?

Meta Pixel does support its own consent management via fbq('consent', 'grant'|'revoke') (Meta Consent Mode), so I've kept the consent path and reworked it to mirror the GA provider — see the updated initializeConsent. debugMode is removed (see the thread below).

chanceaclark · 2025-11-19T16:51:23Z

+      s.parentNode.insertBefore(t,s)}(window, document,'script',
+      'https://connect.facebook.net/en_US/fbevents.js');
+      fbq('init', '${this.config.pixelId}');
+      ${this.config.debugMode ? "fbq('track', 'PageView');" : ''}


Is this manually added or do they have an example with debugMode?

Removed debugMode entirely — unlike GA4's real debug_mode config param, Meta Pixel has no official equivalent (debugging is via the Pixel Helper extension / Events Manager Test Events), so this was hand-rolled. PageView now fires unconditionally after init as the standard base event.

chanceaclark · 2025-11-19T16:53:02Z

+      if (typeof window !== 'undefined' && (window as any).fbq) {
+        (window as any).fbq('consent', 'revoke');


any should be avoided here and anywhere else in the file. Would also love to see if they have a type library we can use so we don't have to type check this, see @types/gtag.js.

Suggested change

if (typeof window !== 'undefined' && (window as any).fbq) {

(window as any).fbq('consent', 'revoke');

if (typeof window !== 'undefined' && 'fbq' in window) {

window.fbq('consent', 'revoke');

Done — added @types/facebook-pixel, which declares a typed global fbq (same mechanism as @types/gtag.js for the GA provider), so all the (window as any).fbq casts are gone and the calls are fully typed.

chanceaclark · 2025-11-19T16:54:37Z

+    // Check consent before initializing
+    if (this.config.consentModeEnabled && this.config.getConsent) {
+      const consent = this.config.getConsent();
+      if (consent && !consent.marketing) {
+        // Consent denied, don't initialize pixel
+        if (this.config.debugMode) {
+          console.log('[Meta Pixel] Consent denied, pixel not initialized');
+        }
+        return;
+      }
+    }


We can probably move this logic into the initializeConsent function.

Refactored — the init-time consent handling now lives in initializeConsent, and the provider no longer skips initialization when consent is denied. It always initializes and applies revoke/grant, matching the GA provider and Meta's recommended Consent Mode flow.

Adds a Meta Pixel (Facebook Pixel) provider to the Catalyst analytics framework, following the GoogleAnalyticsProvider architecture. Merchants who configure a Meta Pixel (surfaced via webAnalytics.metaPixel.pixelId in the GraphQL Storefront API) get standard e-commerce event tracking alongside GA4. - MetaPixelProvider implementing AnalyticsProvider, typed with @types/facebook-pixel (no 'any'). - Meta Consent Mode: fbq('consent', ...) applied before init so the pixel stays dormant until marketing consent is granted. - Standard events (ViewContent, AddToCart) use fbq('track', ...); events with no Meta standard equivalent (ViewCart, RemoveFromCart, ViewCategory) use fbq('trackCustom', ...). Each carries an eventID for browser <-> Conversions API deduplication. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

BC-AdamWard · 2026-07-17T18:30:05Z

Thanks for the review, @chanceaclark — sorry for the long pause on this one! I've refreshed the PR against the latest canary and addressed all the feedback:

No more any: switched to @types/facebook-pixel, which declares a global fbq the same way @types/gtag.js backs the GA provider — so calls are fully typed and there are zero any casts left.
Consent: reworked to mirror GoogleAnalyticsProvider. Meta does have a Consent Mode, so rather than skipping init when consent is denied, the pixel always initializes and applies fbq('consent', 'grant'|'revoke') — before fbq('init') per Meta's docs — so nothing fires until marketing consent is granted.
debugMode: removed. Unlike GA4's real debug_mode param, Meta has no equivalent (debugging is via Pixel Helper / Test Events), so it was hand-rolled — dropped it and the console logging, and fixed the stray debug-gated PageView.
Standard vs custom events: AddToCart/ViewContent use fbq('track', …); ViewCart/RemoveFromCart/ViewCategory (no Meta standard equivalent) use fbq('trackCustom', …). Each event now carries an eventID for browser ↔ Conversions API dedup.

Also — the schema dependency this originally flagged is resolved: webAnalytics.metaPixel { pixelId } now ships in the Storefront API, so the fragment validates and Lint/Typecheck is green. Verified events firing end-to-end with Meta Pixel Helper. Ready for another look 🙏

BC-AdamWard marked this pull request as ready for review November 19, 2025 04:52

BC-AdamWard requested a review from a team November 19, 2025 04:52

chanceaclark reviewed Nov 19, 2025

View reviewed changes

BC-AdamWard force-pushed the feat/add-meta-pixel-analytics-provider branch from 0d7b568 to f6092e4 Compare July 17, 2026 18:29

BC-AdamWard requested a review from a team as a code owner July 17, 2026 18:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Meta Pixel analytics provider support#2727

Add Meta Pixel analytics provider support#2727
BC-AdamWard wants to merge 1 commit into
bigcommerce:canaryfrom
BC-AdamWard:feat/add-meta-pixel-analytics-provider

BC-AdamWard commented Nov 19, 2025 •

edited

Loading

Uh oh!

changeset-bot Bot commented Nov 19, 2025 •

edited

Loading

Uh oh!

vercel Bot commented Nov 19, 2025

Uh oh!

chanceaclark left a comment

Uh oh!

chanceaclark Nov 19, 2025

Uh oh!

BC-AdamWard Jul 17, 2026

Uh oh!

chanceaclark Nov 19, 2025

Uh oh!

BC-AdamWard Jul 17, 2026

Uh oh!

chanceaclark Nov 19, 2025

Uh oh!

BC-AdamWard Jul 17, 2026

Uh oh!

chanceaclark Nov 19, 2025

Uh oh!

BC-AdamWard Jul 17, 2026

Uh oh!

BC-AdamWard commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		getConsent?: () => Analytics.Consent.ConsentValues \| null;
		debugMode?: boolean;

		if (typeof window !== 'undefined' && (window as any).fbq) {
		(window as any).fbq('consent', 'revoke');

Uh oh!

Conversation

BC-AdamWard commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why?

Testing

Migration

Uh oh!

changeset-bot Bot commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Nov 19, 2025

Uh oh!

chanceaclark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BC-AdamWard commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BC-AdamWard commented Nov 19, 2025 •

edited

Loading

changeset-bot Bot commented Nov 19, 2025 •

edited

Loading