> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Meta Pixel

<!-- -->

[Web](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/meta)

<!-- -->

[Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/meta)[ ](https://www.npmjs.com/package/@walkeros/web-destination-meta)

<!-- -->

[Package](https://www.npmjs.com/package/@walkeros/web-destination-meta)

[Meta Pixel (formerly Facebook Pixel)](https://developers.facebook.com/docs/meta-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[​](#installation "Direct link to 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](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This <!-- -->destination<!-- --> uses the standard <!-- -->destination<!-- --> config wrapper (consent, data, env, id, ...). For the shared fields see [destination<!-- --> configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property   | Type     | Description                                       | More |
| ---------- | -------- | ------------------------------------------------- | ---- |
| `pixelId*` | `string` | Your Meta Pixel ID from Facebook Business Manager |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

| Property      | Type                             | Description                                        | More |
| ------------- | -------------------------------- | -------------------------------------------------- | ---- |
| `track`       | `'PageView' \| 'AddPaymentInfo'` | Meta Pixel standard event name to send             |      |
| `trackCustom` | `string`                         | Custom event name for tracking non-standard events |      |

## Examples

### Add to cart

A product add event is mapped to the Meta Pixel AddToCart standard event with product contents 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": "1700000001-gr0up-1",
  "trigger": "click",
  "entity": "product",
  "action": "add",
  "timestamp": 1700000001,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "AddToCart",
  "data": {
    "map": {
      "value": "data.price",
      "currency": {
        "value": "EUR"
      },
      "contents": {
        "set": [
          {
            "map": {
              "id": "data.id",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      },
      "content_type": {
        "value": "product"
      }
    }
  }
}
```

Out

```
fbq("track", "AddToCart", {
  "currency": "EUR",
  "value": 420,
  "contents": [
    {
      "id": "ers",
      "quantity": 1
    }
  ],
  "content_type": "product"
}, {
  "eventID": "1700000001-gr0up-1"
})
```

### Custom event

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": 1700000005,
  "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

```
fbq("trackCustom", "VideoComplete", {
  "video_id": "v1d30",
  "duration": 120
}, {
  "eventID": "1700000005-gr0up-1"
})
```

### Pixel init

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

Event

```
{
  "loadScript": true,
  "settings": {
    "pixelId": "1234567890"
  }
}
```

Out

```
fbq("init", "1234567890")
```

### Initiate checkout

A cart view event is mapped to the Meta Pixel InitiateCheckout standard event with value and product contents.

Event

```
{
  "name": "cart view",
  "data": {
    "currency": "EUR",
    "value": 840
  },
  "context": {
    "shopping": [
      "cart",
      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,
        "quantity": 2
      },
      "context": {
        "shopping": [
          "cart",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "1700000003-gr0up-1",
  "trigger": "load",
  "entity": "cart",
  "action": "view",
  "timestamp": 1700000003,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "InitiateCheckout",
  "data": {
    "map": {
      "value": "data.value",
      "currency": {
        "value": "EUR"
      },
      "contents": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "t=>f(t)&&\"product\"===t.entity"
            },
            "map": {
              "id": "data.id",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      },
      "num_items": {
        "fn": {
          "$code": "t=>t.nested.filter(t=>\"product\"===t.entity).length"
        }
      }
    }
  }
}
```

Out

```
fbq("track", "InitiateCheckout", {
  "currency": "EUR",
  "value": 840,
  "contents": [
    {
      "id": "ers",
      "quantity": 2
    }
  ],
  "num_items": 1
}, {
  "eventID": "1700000003-gr0up-1"
})
```

### Page view

A page view event is forwarded to Meta Pixel as the PageView standard event with no extra parameters.

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": "1700000004-gr0up-1",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000004,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```
fbq("track", "PageView", {}, {
  "eventID": "1700000004-gr0up-1"
})
```

### Purchase

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

Event

```
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 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": "1700000000-gr0up-1",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "Purchase",
  "data": {
    "map": {
      "value": "data.total",
      "currency": {
        "value": "EUR"
      },
      "contents": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "t=>f(t)&&\"product\"===t.entity"
            },
            "map": {
              "id": "data.id",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      },
      "content_type": {
        "value": "product"
      },
      "num_items": {
        "fn": {
          "$code": "t=>t.nested.filter(t=>\"product\"===t.entity).length"
        }
      }
    }
  }
}
```

Out

```
fbq("track", "Purchase", {
  "value": 555,
  "currency": "EUR",
  "contents": [
    {
      "id": "ers",
      "quantity": 1
    },
    {
      "id": "cc",
      "quantity": 1
    }
  ],
  "content_type": "product",
  "num_items": 2
}, {
  "eventID": "1700000000-gr0up-1"
})
```

### View content

A product view event is mapped to the Meta Pixel ViewContent standard event with single-product contents.

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": "1700000002-gr0up-1",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000002,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "ViewContent",
  "data": {
    "map": {
      "value": "data.price",
      "currency": {
        "value": "EUR"
      },
      "content_type": {
        "value": "product"
      },
      "contents": {
        "set": [
          {
            "map": {
              "id": "data.id",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}
```

Out

```
fbq("track", "ViewContent", {
  "currency": "EUR",
  "value": 420,
  "contents": [
    {
      "id": "ers",
      "quantity": 1
    }
  ],
  "content_type": "product"
}, {
  "eventID": "1700000002-gr0up-1"
})
```