Skip to main content
Ask your AI

Meta Pixel

Web Source code Package

Meta Pixel (formerly Facebook Pixel) tracks visitor activity and conversions for Facebook and Instagram advertising campaigns. The destination sends events to the Meta Pixel through its fbq function. Install the destination; mapping events to Meta's format is optional. An event without a rule goes out with fbq('track', ...) under its walkerOS name, such as product add; only page view is renamed, to PageView. With loadScript: true, as in the quickstart, walkerOS also loads the Pixel script.

Where this fits

Meta Pixel is a web destination in the walkerOS flow:

Initializes the fbq function with your pixel ID, loads the Meta Pixel script with loadScript, and tracks page views and custom conversions for Facebook and Instagram ads.

Installation​

npm install @walkeros/collector @walkeros/web-destination-meta
import { startFlow } from '@walkeros/collector';
import destinationMeta from '@walkeros/web-destination-meta';

await startFlow({
  destinations: {
    meta: {
      code: destinationMeta,
      config: {
        loadScript: true,
        settings: {
          pixelId: '1234567890',
        },
      },
    },
  },
});

The quickstart above sets no consent, so the Meta Pixel loads and receives every event without marketing consent, and a revocation changes nothing. Add consent: { marketing: true } to config, next to settings, before you go live: the Pixel then loads once marketing is granted, and events pushed before the grant wait in the queue and are sent then (see consent).

Configuration​

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
pixelId*stringYour Meta Pixel ID from Facebook Business Manager
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
trackMeta Pixel standard event name to send
trackCustomstringCustom event name for tracking non-standard events

Examples

Add to cart

A product add is mapped to the Meta Pixel AddToCart standard event with product contents, currency and value.

Event
{
  "name": "product add",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "quantity": 1,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "intent",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "83e860384d50953f",
  "trigger": "click",
  "entity": "product",
  "action": "add",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "AddToCart",
  "data": {
    "map": {
      "content_type": {
        "value": "product"
      },
      "contents": {
        "set": [
          {
            "map": {
              "id": "data.id",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      },
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "value": "data.price"
    }
  }
}
Out
window.fbq("track", "AddToCart", {
  "content_type": "product",
  "contents": [
    {
      "id": "ers",
      "quantity": 1
    }
  ],
  "currency": "EUR",
  "value": 420
}, {
  "eventID": "83e860384d50953f"
})

Pixel init

The destination loads the Meta Pixel script and initializes it with the configured pixelId.

Event
{
  "loadScript": true,
  "settings": {
    "pixelId": "1234567890"
  }
}
Out
window.fbq("init", "1234567890")

Page view

A page view is sent to Meta Pixel as the PageView standard event, with the event id for deduplication.

Event
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f0cc5f6fec3d8eeb",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Out
window.fbq("track", "PageView", {}, {
  "eventID": "f0cc5f6fec3d8eeb"
})

Purchase

An order complete is mapped to the Meta Pixel Purchase standard event with value, currency, product contents and item count.

Event
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "value": 462,
    "tax": 73.76,
    "shipping": 5.22,
    "total": 467.22
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "235d0d7bd7a213f2",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "Purchase",
  "data": {
    "map": {
      "content_type": {
        "value": "product"
      },
      "contents": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
            },
            "map": {
              "id": "data.id",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      },
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "num_items": {
        "fn": {
          "$code": "e=>\"object\"==typeof e&&null!==e&&\"nested\"in e&&Array.isArray(e.nested)?e.nested.filter(e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity).length:0"
        }
      },
      "value": "data.value"
    }
  }
}
Out
window.fbq("track", "Purchase", {
  "content_type": "product",
  "contents": [
    {
      "id": "ers",
      "quantity": 1
    },
    {
      "id": "cc",
      "quantity": 1
    }
  ],
  "currency": "EUR",
  "num_items": 2,
  "value": 462
}, {
  "eventID": "235d0d7bd7a213f2"
})

View content

A product view is mapped to the Meta Pixel ViewContent standard event with product contents, currency and value.

Event
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "db22fb16c70f663d",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "ViewContent",
  "data": {
    "map": {
      "content_type": {
        "value": "product"
      },
      "contents": {
        "set": [
          {
            "map": {
              "id": "data.id",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      },
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "value": "data.price"
    }
  }
}
Out
window.fbq("track", "ViewContent", {
  "content_type": "product",
  "contents": [
    {
      "id": "ers",
      "quantity": 1
    }
  ],
  "currency": "EUR",
  "value": 420
}, {
  "eventID": "db22fb16c70f663d"
})

Custom events​

Set trackCustom in a rule's settings to send an event that is not one of Meta's standard events. The destination then calls fbq('trackCustom', name, params, { eventID }) instead of fbq('track', ...); the eventID is the walkerOS event ID, which the Conversions API matches, together with the event name, to deduplicate.

A video complete event is sent as a Meta Pixel trackCustom call with a custom event name and parameters.

Event
{
  "name": "video complete",
  "data": {
    "video_id": "v1d30",
    "duration": 120
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "1700000005-gr0up-1",
  "trigger": "test",
  "entity": "video",
  "action": "complete",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "settings": {
    "trackCustom": "VideoComplete"
  },
  "data": {
    "map": {
      "video_id": "data.video_id",
      "duration": "data.duration"
    }
  }
}
Out
window.fbq("trackCustom", "VideoComplete", {
  "video_id": "v1d30",
  "duration": 120
}, {
  "eventID": "1700000005-gr0up-1"
})

A destination with config.consent calls fbq('consent', 'revoke') when the required consent is revoked and fbq('consent', 'grant') when it is granted. A blocked fbevents.js fails later events visibly, and a missing pixelId is a config error. A rule with silent: true sends no event. A rule whose data resolves to something other than an object is sent with empty parameters, and its push answers done.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)