Meta Pixel
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.
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- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationMeta from '@walkeros/web-destination-meta';
await startFlow({
destinations: {
meta: {
code: destinationMeta,
config: {
loadScript: true,
settings: {
pixelId: '1234567890',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "web"
},
"destinations": {
"meta": {
"package": "@walkeros/web-destination-meta",
"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
| Property | Type | Description | More |
|---|---|---|---|
pixelId | string | Your Meta Pixel ID from Facebook Business Manager |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
track | Meta Pixel standard event name to send | ||
trackCustom | string | Custom 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.
{
"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"
}
}{
"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"
}
}
}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.
{
"loadScript": true,
"settings": {
"pixelId": "1234567890"
}
}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.
{
"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"
}
}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.
{
"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"
}
}{
"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"
}
}
}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.
{
"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"
}
}{
"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"
}
}
}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.
{
"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"
}
}{
"settings": {
"trackCustom": "VideoComplete"
},
"data": {
"map": {
"video_id": "data.video_id",
"duration": "data.duration"
}
}
}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.