Meta Conversion API

Source code Package

The Meta Conversion API (CAPI) destination is used to send server-side events from walkerOS to the Facebook Conversion API. It handles the data transformation and ensures that your events are correctly formatted for the Meta Conversion API.

Dependencies

Before using the Meta destination, ensure you have:

• walkerOS node source installed

• Conversion API requirements

Installation

To get started, install the package via npm:

npm install @elbwalker/destination-node-meta

Configuration

Example

Configuration

{
  pixelId: "p1x3l1d",
  accessToken: "s3cr3t",
  user_data: {
    external_id: {
      set: [
        "user.device",
        "user.session"
      ]
    }
  }
}

{ pixelId: "p1x3l1d", accessToken: "s3cr3t", user_data: { external_id: { set: [ "user.device", "user.session" ] } } }

Result

sendNode('https://graph.facebook.com/v22.0/p1x3l1d/events?access_token=s3cr3t', {
  data: [
    {
      event_id: "1746576817000-gr0up-1",
      event_time: 1746576817,
      action_source: "website",
      user_data: {
        external_id: [
          "cc8e27118413234d4297ed00a02711365312c79325df9b5b8f4199cbd0b96e7e",
          "9176e6f336dbdb4f99b0e45cbd7e41e0e2323812b236822842a61ffbd362ac8c",
        ],
      },
      event_source_url: "https://localhost:80",
      // ... event data
    },
  ],
});

sendNode('https://graph.facebook.com/v22.0/p1x3l1d/events?access_token=s3cr3t', { data: [ { event_id: "1746576817000-gr0up-1", event_time: 1746576817, action_source: "website", user_data: { external_id: [ "cc8e27118413234d4297ed00a02711365312c79325df9b5b8f4199cbd0b96e7e", "9176e6f336dbdb4f99b0e45cbd7e41e0e2323812b236822842a61ffbd362ac8c", ], }, event_source_url: "https://localhost:80", // ... event data }, ], });

The parameters event_name, event_id, event_time, action_source, and user_data (and event_source_url for website events) are set automatically.

Custom

Property	Type	Description
accessToken*	string	Ads account ID used for every conversion
pixelId*	string	Ads account ID used for every conversion
action_source	string	The source of the event (e.g., website, app)
doNotHash	string[]	List of properties to not hash
test_event_code	string	Test event code
url	string	The URL of the page where the event occurred
user_data	object	Customer Information Parameters

Mapping

The complete list of all parameters can be found in the Server Event Parameters documentation. Some events require specific parameters.

User Data

At least one user_data parameter is required. These are crucial for matching events to the correct user. It can be set on custom.user_data level, with the data.map.user_data config, or on the event level with mapping.entity.action.user_data. All values will be merged together.

The user_data.fbclid parameter is automatically formatted the fbc value. It is usually available with session start events in data.fbclid.

Destination Config

{
  custom: {
    pixelId: 'p1x3l1d',
    accessToken: 's3cr3t',
    user_data: {
      external_id: { set: ['user.device', 'user.session'] },
    },
    doNotHash: ['external_id'],
  },
  data: {
    map: {
      user_data: {
        map: {
          fn: { value: 'elb' },
        },
      },
    },
  },
  mapping: {
    entity: {
      action: {
        data: {
          map: {
            user_data: {
              map: {
                ph: { value: '123' },
              },
            },
          },
        },
      },
    },
  }
}

{ custom: { pixelId: 'p1x3l1d', accessToken: 's3cr3t', user_data: { external_id: { set: ['user.device', 'user.session'] }, }, doNotHash: ['external_id'], }, data: { map: { user_data: { map: { fn: { value: 'elb' }, }, }, }, }, mapping: { entity: { action: { data: { map: { user_data: { map: { ph: { value: '123' }, }, }, }, }, }, }, } }

Result

{
  user_data: {
    // from custom user_data
    external_id: ['c00k13', 's3ss10n'],
    // from destination config data
    fn: '3534f80438f9c1175a229f952c99c2232a24c423a392bdaf116cad54d9d9676c',
    // from mapping
    ph: 'a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3',
    // more available customer information parameters to set
    // em (email)
    // ln (last name)
    // db (date of birth)
    // ge (gender)
    // ct (city)
    // st (state)
    // zp (zip)
    // country (country)
    // client_ip_address (client ip address)
    // client_user_agent (client user agent)
    // fbc (facebook click id)
    // fbp (facebook browser id)
    // subscription_id (subscription id)
    // fb_login_id (facebook login id)
    // ig_account_id (instagram account id)
    // ig_sid (instagram scoped user id)
    // lead_id (lead id)
    // anon_id (anonymous id)
    // madid (mobile advertiser id)
    // page_id (page id)
    // page_scoped_user_id (page scoped user id)
    // ctwa_clid (click to whatsapp ad click id)
  },
  // ... other parameters
}

{ user_data: { // from custom user_data external_id: ['c00k13', 's3ss10n'], // from destination config data fn: '3534f80438f9c1175a229f952c99c2232a24c423a392bdaf116cad54d9d9676c', // from mapping ph: 'a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3', // more available customer information parameters to set // em (email) // ln (last name) // db (date of birth) // ge (gender) // ct (city) // st (state) // zp (zip) // country (country) // client_ip_address (client ip address) // client_user_agent (client user agent) // fbc (facebook click id) // fbp (facebook browser id) // subscription_id (subscription id) // fb_login_id (facebook login id) // ig_account_id (instagram account id) // ig_sid (instagram scoped user id) // lead_id (lead id) // anon_id (anonymous id) // madid (mobile advertiser id) // page_id (page id) // page_scoped_user_id (page scoped user id) // ctwa_clid (click to whatsapp ad click id) }, // ... other parameters }

The values em, ph, fn, ln, db, ge, ct, st, zp, country, and external_id are automatically hashed. The doNotHash property can be used to exclude specific parameters from being hashed.

Purchase

Event

{
  event: "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: [
    {
      type: "product",
      data: {
        id: "ers",
        name: "Everyday Ruck Snack",
        color: "black",
        size: "l",
        price: 420
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "product",
      data: {
        id: "cc",
        name: "Cool Cap",
        size: "one size",
        price: 42
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "gift",
      data: {
        name: "Surprise"
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    }
  ],
  consent: {
    functional: true
  },
  id: "1747095217000-gr0up-1",
  trigger: "load",
  entity: "order",
  action: "complete",
  timestamp: 1747095217000,
  timing: 3.14,
  group: "gr0up",
  count: 1,
  version: {
    source: "0.0.7",
    tagging: 1
  },
  source: {
    type: "web",
    id: "https://localhost:80",
    previous_id: "http://remotehost:9001"
  }
}

{ event: "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: [ { type: "product", data: { id: "ers", name: "Everyday Ruck Snack", color: "black", size: "l", price: 420 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "product", data: { id: "cc", name: "Cool Cap", size: "one size", price: 42 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "gift", data: { name: "Surprise" }, context: { shopping: [ "complete", 0 ] }, nested: [] } ], consent: { functional: true }, id: "1747095217000-gr0up-1", trigger: "load", entity: "order", action: "complete", timestamp: 1747095217000, timing: 3.14, group: "gr0up", count: 1, version: { source: "0.0.7", tagging: 1 }, source: { type: "web", id: "https://localhost:80", previous_id: "http://remotehost:9001" } }

Custom Config

{
  name: 'Purchase',
  data: {
    map: {
      order_id: 'data.id',
      currency: {
        key: 'data.currency',
        value: 'EUR'
      },
      value: 'data.total',
      contents: {
        loop: [
          'nested',
          {
            condition: (entity) =>
              isObject(entity) && entity.type === 'product',
            map: {
              id: 'data.id',
              item_price: 'data.price',
              quantity: {
                key: 'data.quantity',
                value: 1,
              },
            },
          },
        ],
      },
      num_items: {
        fn: (event) =>
          (event as WalkerOS.Event).nested.filter(
            (item) => item.type === 'product',
          ).length,
      },
    },
  },
}

{ name: 'Purchase', data: { map: { order_id: 'data.id', currency: { key: 'data.currency', value: 'EUR' }, value: 'data.total', contents: { loop: [ 'nested', { condition: (entity) => isObject(entity) && entity.type === 'product', map: { id: 'data.id', item_price: 'data.price', quantity: { key: 'data.quantity', value: 1, }, }, }, ], }, num_items: { fn: (event) => (event as WalkerOS.Event).nested.filter( (item) => item.type === 'product', ).length, }, }, }, }

Result

sendNode('https://graph.facebook.com/v22.0/p1x3l1d/events?access_token=s3cr3t', {
  data: [
    {
      event_name: "Purchase",
      event_id: "1746576817000-gr0up-1",
      event_time: 1746576817,
      action_source: "website",
      order_id: "0rd3r1d",
      currency: "EUR",
      value: 555,
      contents: [
        {
          id: "ers",
          item_price: 420,
          quantity: 1,
        },
        {
          id: "cc",
          item_price: 42,
          quantity: 1,
        },
      ],
      num_items: 2,
      event_source_url: "https://localhost:80",
    },
  ],
});

sendNode('https://graph.facebook.com/v22.0/p1x3l1d/events?access_token=s3cr3t', { data: [ { event_name: "Purchase", event_id: "1746576817000-gr0up-1", event_time: 1746576817, action_source: "website", order_id: "0rd3r1d", currency: "EUR", value: 555, contents: [ { id: "ers", item_price: 420, quantity: 1, }, { id: "cc", item_price: 42, quantity: 1, }, ], num_items: 2, event_source_url: "https://localhost:80", }, ], });

info

If you need professional support with your walkerOS implementation, check out our services.