Ask your AI

Meta Pixel

Meta Pixel (formerly Facebook Pixel) tracks visitor activity and conversions for Facebook and Instagram advertising campaigns. The destination automatically sends events to Meta Pixel via fbq function. All you need to do is install the destination, and optionally map events to Meta's format. walkerOS takes care of loading the script and the function calls.

Where this fits

Meta Pixel is a web destination in the walkerOS flow:

Loads Meta Pixel script dynamically, initializes the fbq function with your pixel ID, and tracks page views and custom conversions for Facebook and Instagram ads.

Installation

npm install @walkeros/web-destination-meta

Integrated
Bundled

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

const { collector, elb } = await startFlow({
  destinations: {
    meta: {
      code: destinationMeta,
      config: {
        settings: {
          pixelId: '1234567890', // Your Meta Pixel ID
        },
        loadScript: true, // Load Meta Pixel script automatically
      },
    },
  },
});

Add to your flow.json destinations:

"destinations": {
  "meta": {
    "package": "@walkeros/web-destination-meta",
    "config": {
      "settings": {
        "pixelId": "1234567890"
      },
      "loadScript": true
    }
  }
}

See bundled mode setup | CLI reference

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

* Required fields

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.

Event

{
  "name": "product add",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "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",
    "shipping": 5.22,
    "taxes": 73.76,
    "value": 555
  },
  "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": 555
}, {
  "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
  },
  "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 can use for deduplication.

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.

💡 Need implementation support?

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

Installation​

Configuration​

Settings​

Mapping​

Examples

Add to cart

Pixel init

Page view

Purchase

View content

Custom events​

Installation

Configuration

Settings

Mapping

Custom events