meta-pixel

TypeScript implementation of the facebook's pixel script. This is a client-side only library.

Installation

npm i meta-pixel

Usage

Manually setup pixels

import { addScriptDefault } from 'meta-pixel'

const fbq = addScriptDefault()
fbq('set', 'autoConfig', true, 'pixel_01')
fbq('init', 'pixel_01')
fbq('track', 'PageView')

Using setup & multi pixels

import { setup } from 'meta-pixel'

const { $fbq } = setup()
  .init('pixel_01')
  .init('pixel_02', false)
  .pageView()

$fbq('track', 'CompleteRegistration')

Combining both

import { addScriptDefault, setup } from 'meta-pixel'

const fbq = addScriptDefault()
setup(fbq)
  .init('pixel_01')
  .init('pixel_02')
  .pageView()

fbq('track', 'CompleteRegistration')

Manually define fbevents script

- const fbq = metapixel.addScriptDefault()
+ const fbq = metapixel.addScript(window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js')

API

setup($fbq?) returns a chainable controller. Pass your own FacebookQuery (e.g. from addScriptDefault()) or let it create one.

| Member | Description | | --- | --- | | $fbq | The underlying Facebook query function — use it for raw, fully typed calls like $fbq('track', 'Purchase', { value: 9.99, currency: 'EUR' }). | | init(pixelId, autoConfig = true, advancedMatching?) | Initialize a pixel. autoConfig maps to fbq('set', 'autoConfig', …). advancedMatching (typed InitData) forwards customer data — email, phone, etc., all strings — for better attribution. | | pageView(pixelId?) | Send a PageView. With an id it uses trackSingle; without one it tracks every pixel. | | consent('grant' \| 'revoke') | Global GDPR consent — the command takes no pixel id, so it applies to all pixels. Call 'revoke' before init to hold delivery until you grant it. |

init, pageView and consent are chainable (they return the controller). Standard events and their parameters are typed — e.g. Purchase requires currency and value, and advanced-matching fields are strings.

import { setup } from 'meta-pixel'

setup()
  .consent('revoke')   // hold delivery until the user opts in
  .init('pixel_01')
  .pageView()

Pass advanced matching to improve attribution (every field is a string):

import { setup } from 'meta-pixel'

setup()
  .init('pixel_01', true, { em: '[email protected]', ph: '16505554444', db: '19910526' })
  .pageView()

Resources

• https://developers.facebook.com/docs/meta-pixel/get-started/
• https://developers.facebook.com/docs/meta-pixel/advanced/#automatic-configuration