Facebook Conversion API

Node.js wrapper for Facebook's Conversion API

This JS/TS library allows you to track events with Facebook's Conversion API, whether on the client-side or server-side, helping you capture more accurate data for your Facebook ad campaigns.

Install

npm install @cataline/facebook-conversion-api

Usage

Set up the library with your credentials and settings.

import { facebookConversionAPI } from '@cataline/facebook-conversion-api'

facebookConversionAPI.init({
  accessToken: 'YOUR_ACCESS_TOKEN',
  pixelId: 'YOUR_PIXEL_ID',
  actionSource: 'website',
})

Read more on how to get your access token.

Setting User Data

The more user information you provide, the better the event attribution.

facebookConversionAPI.setUserData({
  emails: ['[email protected]', '[email protected]'],
  phones: ['+1234567890', '+0987654321'],
  firstName: 'john',
  lastName: 'doe',
  dateOfBirth: '19970216',
  gender: 'm',
  city: 'São Paulo',
  state: 'SP',
  zip: '01100000',
  country: 'br',
  clientIpAddress: '192.168.1.1',
  clientUserAgent: navigator.userAgent,
  fbc: 'fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890',
  fbp: 'fb.1.1558571054389.1098115397',
  facebookLoginId: '1234567890',
  externalId: '123456789',
})

Learn how to obtain fbp/fpc identifiers.

We will hash the required data using SHA-256, but you must provide the rest according to Facebook’s documentation to ensure accurate and effective event tracking.

Sending Events

Send events to Facebook Conversion API. This method supports all standard Facebook pixel events and custom events.

facebookConversionAPI.trackEvent({
  name: 'Purchase', // Use standard event name or custom event name
  id: 'unique-event-id', // Optional: for deduplication
  sourceUrl: 'https://your-site.com/thank-you',
  params: {
    currency: 'USD',
    value: 99.99,
    contents: [
      {
        id: 'product123',
        quantity: 1,
        delivery_category: 'home_delivery',
      },
    ],
  },
})

Event Deduplication

Understand how event deduplication works using event IDs.

License

This project is licensed under the MIT License.