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

# Meta Pixel

[Web](#)[ Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/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")

```bash
npm install @walkeros/web-destination-meta
```

* Integrated
* Bundled

```typescript
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:

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

[See bundled mode setup](/preview/pr-749/docs/getting-started/modes/bundled.md) | [CLI reference](/preview/pr-749/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](/docs/destinations#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](/docs/mapping).

| 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

```json
{
  "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

```json
{
  "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

```javascript
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

```json
{
  "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

```json
{
  "settings": {
    "trackCustom": "VideoComplete"
  },
  "data": {
    "map": {
      "video_id": "data.video_id",
      "duration": "data.duration"
    }
  }
}
```

Out

```javascript
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

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

Out

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

### Initiate checkout

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

Event

```json
{
  "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

```json
{
  "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

```javascript
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

```json
{
  "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

```javascript
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

```json
{
  "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

```json
{
  "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

```javascript
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

```json
{
  "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

```json
{
  "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

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