Facebook Pixel Destination Config Reference

Facebook Pixel is an advertising destination. RudderStack loads the Meta Pixel in the browser for web sources in device mode, and sends events to Meta’s Conversions API from its servers in cloud mode.

In a Facebook Pixel destination spec:

• type: facebook_pixel
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: fb-pixel-prod
spec:
  id: fb-pixel-prod
  display_name: Facebook Pixel Production
  type: facebook_pixel
  definition_version: 1
  enabled: true
  config:
    pixel_id: "{{ .FB_PIXEL_ID }}"
    access_token: "{{ .FB_ACCESS_TOKEN }}"

    standard_page_call: false
    value_field_identifier: properties.price
    advanced_mapping: true
    use_updated_mapping: true
    events_to_events:
      - from: Order Completed
        to: Purchase

    limited_data_usage: false
    test_destination: false
    remove_external_id: false
    blacklist_pii_properties:
      - property: email
        hash: true

    auto_config:
      web: true
    legacy_conversion_pixel_id:
      - from: Signed Up
        to: "{{ .FB_LEGACY_PIXEL_ID }}"

    connection_mode:
      web: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - marketing

The above example loads the Pixel on web sources in device mode and sends server-side events in cloud mode. Because a source connects in cloud mode, it needs access_token — see Access token requirements.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

In cloud mode Facebook Pixel accepts identify, page, screen, and track events. In device mode, web sources send page and track.

Access token requirements

The Conversions API needs access_token; the Pixel in the browser doesn’t. Rudder CLI checks for it twice:

• On the destination. access_token is required unless connection_mode is set and either maps web to device or leaves web out. A spec with no connection_mode at all, or with web: cloud, must carry it.
• On each connection. Connecting any source in cloud mode requires access_token — only web in device mode is exempt. See Connect a source.

In practice: if anything connects in cloud mode, set access_token.

Connection

Event settings

Testing and privacy

The dashboard asks for test_event_code when test_destination is on. Rudder CLI doesn’t enforce that pairing.

Web device mode

These keys configure the Pixel in the browser, so they apply only when connection_mode.web is device.

legacy_conversion_pixel_id:
  - from: Signed Up
    to: "{{ .FB_LEGACY_PIXEL_ID }}"

Event filtering

Client-side event filtering is applied by the RudderStack SDK, so it affects only web sources connected in device mode. Events sent in cloud mode aren’t filtered by it.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode:
  web: device
  cloud: cloud

Source types

Facebook Pixel accepts events from these source types in the mentioned connection modes:

Only web offers device mode, which loads the Meta Pixel in the browser. See Facebook Pixel device mode.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers Facebook Pixel to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify are invalid here.

Connect a source

An event stream connection to this destination is checked against three rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. Every type an event stream source can resolve to is supported here, so this check always passes.

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'fb-pixel-prod' config has no 'connection_mode' entry for source type 'web'

A source connecting in cloud mode needs access_token. Every source type requires it in cloud mode; only web in device mode doesn’t. Without it:

destination 'fb-pixel-prod' config is missing fields required to connect a 'cloud' source: access_token

Secrets

Rudder CLI treats three keys as secrets: pixel_id, access_token, and every legacy_conversion_pixel_id entry’s to value. Write each one you use as a {{ .VAR }} reference and supply the value at apply time:

config:
  pixel_id: "{{ .FB_PIXEL_ID }}"
  access_token: "{{ .FB_ACCESS_TOKEN }}"

export RUDDER_FB_PIXEL_ID="..."
export RUDDER_FB_ACCESS_TOKEN="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

• rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.
• In device mode the Pixel IDs are embedded in the page’s JavaScript, so masking them protects your YAML, not the values themselves.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

For changes across every destination type, see Destination Type Changes by Release.

See more

• Facebook Pixel Destination for the Pixel ID, access token, updated mappings, and fbc and fbp parameters
• Facebook Conversions Destination Config Reference for the server-side-only destination
• Destination Type Reference for Rudder CLI for the rules shared across destination types