Meta Pixel (JS/TS)

The most powerful and developer-friendly Meta Pixel integration for JavaScript & TypeScript applications.

A platform-agnostic wrapper for Meta Pixel that provides a seamless, type-safe experience with advanced features like event deduplication, multiple pixel support, and beautiful debug logging.

📚 Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Configuration
• Standard Events
• Event Data Parameters
• Advanced Usage
• TypeScript Support
• Troubleshooting
• Official Documentation
• License

✨ Features

• ✅ Typescript Support - Full TypeScript support with autocomplete for all official events and parameters
• 🎯 Custom Events Support - Track custom events with full type safety and flexible data structures
• 🚦 Event Deduplication - Support for preventing duplicate events with event IDs
• 🔌 Multiple Pixels Support - Load and manage multiple pixel IDs effortlessly
• 🐛 Debug Mode - Beautiful styled console logs for development and debugging
• 🏠 Localhost Support - Easy configuration to enable/disable tracking on localhost

⚡ Quick Start

npm install @adkit.so/meta-pixel

import META from '@adkit.so/meta-pixel';

// 1. Initialize
META.init({ pixelIds: 'YOUR_PIXEL_ID' });

// 2. Track events
META.track('Purchase', { value: 99.99, currency: 'USD' });

That's it! 🎉

📦 Installation

npm install @adkit.so/meta-pixel

💡 Usage

Basic Initialization

Initialize the pixel as early as possible in your application entry point (e.g., main.ts, App.jsx, index.js).

import META from '@adkit.so/meta-pixel';

META.init({
    pixelIds: '1234567890',
    autoTrackPageView: true, // default: true
});

Tracking Events

// Track standard events
META.track('AddToCart', {
    value: 29.99,
    currency: 'USD',
    content_ids: ['SKU_123'],
    content_type: 'product',
});

// Track custom events
META.trackCustom('MyCustomEvent', {
    custom_param: 'value',
});

Multiple Instances

If you need separate instances for different parts of your application (rare):

import { createMetaPixel } from '@adkit.so/meta-pixel';

const marketingPixel = createMetaPixel();
marketingPixel.init({ pixelIds: 'MARKETING_ID' });

const productPixel = createMetaPixel();
productPixel.init({ pixelIds: 'PRODUCT_ID' });

⚙️ Configuration

Configuration Options

| Option | Type | Default | Description | | ------------------- | -------------------- | ------- | --------------------------------------------------- | | pixelIds | string \| string[] | '' | Required. Single pixel ID or array of pixel IDs | | autoTrackPageView | boolean | true | Automatically track PageView on initialization | | debug | boolean | false | Enable styled console logs with background colors | | enableLocalhost | boolean | false | Enable tracking on localhost (useful for testing) |

Multiple Pixels Example

META.init({
    pixelIds: ['PIXEL_ID_1', 'PIXEL_ID_2', 'PIXEL_ID_3'],
    debug: true,
});

📊 Standard Events

All Meta Pixel standard events are supported with full TypeScript autocomplete. These events help you track important actions on your website and optimize your ad campaigns.

| Event | Description | Common Use Cases | | ---------------------- | ----------------------------- | ----------------------------- | | AddPaymentInfo | Payment info added | Checkout flow | | AddToCart | Item added to shopping cart | E-commerce | | AddToWishlist | Item added to wishlist | E-commerce | | CompleteRegistration | User completed registration | Sign-ups, account creation | | Contact | User contacted business | Contact forms | | CustomizeProduct | Product customization started | Product configurators | | Donate | Donation made | Non-profits | | FindLocation | Location finder used | Store locators | | InitiateCheckout | Checkout process started | E-commerce funnels | | Lead | Lead submitted | Lead generation forms | | Purchase | Purchase completed | Transaction confirmation | | Schedule | Appointment scheduled | Booking systems | | Search | Search performed | Site search | | StartTrial | Trial started | SaaS applications | | SubmitApplication | Application submitted | Job boards, loan applications | | Subscribe | Subscription started | Newsletters, subscriptions | | ViewContent | Content viewed | Product pages, blog posts |

You can find the official list of standard events here.

📋 Event Data Parameters

All event parameters are optional but help improve ad targeting and conversion tracking.

| Parameter | Type | Description | Example | | ------------------ | ----------------------- | ------------------------------------ | -------------------------------- | | value | number | Monetary value of the event | 99.99 | | currency | string | ISO 4217 currency code | 'USD', 'EUR', 'GBP' | | content_ids | string[] | Product IDs or SKUs | ['SKU_123', 'SKU_456'] | | content_type | string | Type of content | 'product', 'product_group' | | content_name | string | Name of page/product | 'Blue T-Shirt' | | content_category | string | Category of page/product | 'Apparel', 'Electronics' | | contents | Array<{id, quantity}> | Detailed product information | [{id: 'SKU_123', quantity: 2}] | | num_items | number | Number of items | 3 | | search_string | string | Search query | 'running shoes' | | status | boolean | Registration/subscription status | true | | predicted_ltv | number | Predicted lifetime value of customer | 450.00 |

You can find the list of properties here

🚀 Advanced Usage

Event Deduplication

Prevent duplicate event tracking by using unique event IDs. This is crucial when tracking conversions from both client and server (CAPI).

const orderId = '12345';

META.track(
    'Purchase',
    {
        value: 299.99,
        currency: 'USD',
        content_ids: ['SKU_123'],
    },
    {
        eventID: `order-${orderId}`, // Unique Event ID
    },
);

Check if Pixel is Loaded

Useful if you need to conditionally run logic based on whether the pixel script has loaded.

if (META.isLoaded()) {
    META.track('Purchase', { value: 99.99, currency: 'USD' });
} else {
    console.log('Pixel not loaded yet');
}

Debug Mode

When debug: true is passed to init(), you'll see beautiful styled console logs:

• 🔵 [Meta Pixel] Info messages (blue background)
• ✅ [Meta Pixel] Success messages (green background)
• ⚠️ [Meta Pixel] Warning messages (orange background)

META.init({
    pixelIds: 'YOUR_ID',
    debug: true,
});

📝 TypeScript Support

This package is written in TypeScript and bundles type definitions.

import type { StandardEvent, EventData, MetaPixelConfig } from '@adkit.so/meta-pixel';

const config: MetaPixelConfig = {
    pixelIds: '123',
};

const eventData: EventData = {
    value: 100,
    currency: 'USD',
};

❓ Troubleshooting

Pixel not loading?

1. Check your pixel ID - Make sure it's correct in your config
2. Enable debug mode - Set debug: true in init() to see detailed logs
3. Check browser console - Look for errors or warnings
4. Check Ad Blockers - Ad blockers often block the Meta Pixel script
5. Enable on localhost - Set enableLocalhost: true if testing locally

Events not showing in Meta Events Manager?

• Wait a few minutes - Events can take 5-20 minutes to appear
• Check Test Events - Use the Test Events tool in Meta Events Manager
• Verify event names - Standard events are case-sensitive

📚 Official Documentation

Learn more about Meta Pixel from official Facebook resources:

• Meta Pixel Reference - Complete API reference
• Standard Events Guide - Detailed event documentation
• Object Properties Reference - All available event parameters
• Conversions API - Server-side event tracking
• Events Manager - Monitor your pixel events

🔗 Platform Packages

Using a framework? Check out our dedicated packages:

• Nuxt - @adkit.so/meta-pixel-nuxt
• React - @adkit.so/meta-pixel-react
• Next.js - @adkit.so/meta-pixel-next

📖 Full Guide

For a complete step-by-step guide on installing and configuring Meta Pixel, check out our detailed tutorial:

How to Install Meta Pixel

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

MIT

Made with ❤️ by Adkit

If this package helped you, please consider giving it a ⭐️ on GitHub!