npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-use-facebook-pixel

v1.0.5

Published

Typed wrapper around Facebook Pixel

Downloads

436

Readme

react-use-facebook-pixel

react-use-facebook-pixel is a lightweight React hook library for integrating Facebook Pixel with your React application. It provides an easy way to initialize and track events with Facebook Pixel, allowing you to measure the effectiveness of your ads and understand user interactions.

Features

  • Automatic Initialization: Initialize Facebook Pixel with optional automatic page view tracking.
  • Event Tracking: Track various events such as AddToCart, Purchase, Lead, and more.
  • Debug Mode: Optional debug mode to log initialization and event tracking information.
  • Customizable Configuration: Set external IDs, configure automatic tracking, and more.

Installation

Install the package via npm or yarn:

npm install react-use-facebook-pixel
yarn add react-use-facebook-pixel

Usage

Initialization

Create an instance of FacebookPixel and initialize it with your pixel ID:

// src/hooks/useFacebookPixel.ts
import { useEffect, useState } from 'react';
import { FacebookPixel } from 'react-use-facebook-pixel';

const useFacebookPixel = () => {
  const [facebookPixel, setFacebookPixel] = useState<FacebookPixel | null>(null);

  useEffect(() => {
    const initializeFacebookPixel = async () => {
      const pixel = new FacebookPixel({
        pixelID: 'PIXEL_ID',
      });

      pixel.init({});

      setFacebookPixel(pixel);
    };

    initializeFacebookPixel();
  }, []);

  return facebookPixel;
};

export default useFacebookPixel;

Tracking Events

Track simple events

pixel.trackEvent('ViewContent', {
  content_ids: ['1234'],
});

Track events with optional data and additional information:

pixel.trackEvent(
  'Purchase',
  {
    content_ids: ['1234', '5678'],
    content_type: 'product',
    contents: [{ id: '1234', quantity: 1 }],
    currency: 'USD',
    value: 100.0,
  },
  {
    eventID: 'd2e6f4f5-8b43-4d4e-bd45-9d9e5e6b2d9a',
  }
);

Or use types for events & events data:

import { AdditionalEventData, EventData, TrackableEventNameEnum } from 'react-use-facebook-pixel';

const eventData: EventData[TrackableEventNameEnum.Purchase] = {
  content_ids: ['21312'],
  currency: 'USD',
  value: 1
};

const additionalEventData: AdditionalEventData = {
  eventID: 'd2e6f4f5-8b43-4d4e-bd45-9d9e5e6b2d9a'
};

facebookPixel.trackEvent(TrackableEventNameEnum.Purchase, eventData, additionalEventData);

Available Events

  • AddPaymentInfo
  • AddToCart
  • AddToWishlist
  • CompleteRegistration
  • Contact
  • CustomizeProduct
  • Donate
  • FindLocation
  • InitiateCheckout
  • Lead
  • Purchase
  • Schedule
  • Search
  • StartTrial
  • SubmitApplication
  • Subscribe
  • ViewContent
  • PageView

API Reference

FacebookPixel

Constructor

new FacebookPixel(props: Props)
  • pixelID (string): Your Facebook Pixel ID.
  • debug (boolean, optional): Enable or disable debug mode (default: true).
  • pageViewOnInit (boolean, optional): Automatically track PageView event on initialization (default: true).
  • autoConfig (boolean, optional): Enable automatic configuration (default: true).

Methods

  • init(props: InitProps): Initializes the Facebook Pixel with optional properties.
  • setExternalId(externalId: string): Sets an external ID for tracking.
  • getExternalId(): Retrieves the current external ID.
  • trackEvent<K extends TrackableEventName>(eventName: K, data?: EventData[K], additionalData?: AdditionalEventData): Tracks an event with optional data and additional information.

Configuration Options

Props Interface

  • pixelID (string): Your Facebook Pixel ID.
  • pageViewOnInit (boolean, optional): Automatically track PageView event on initialization.
  • debug (boolean, optional): Enable or disable debug mode.
  • autoConfig (boolean, optional): Enable or disable automatic configuration.

InitProps Interface

  • external_id (string, optional): Unique ID from the advertiser.
  • em (string, optional): Email (unhashed lowercase or hashed SHA-256).
  • fn (string, optional): First name (lowercase letters).
  • ln (string, optional): Last name (lowercase letters).
  • ph (number, optional): Phone number (digits only).
  • ge (string, optional): Gender (single lowercase letter: 'f' or 'm').
  • db (number, optional): Birthdate (digits only: YYYYMMDD).
  • ct (string, optional): City (lowercase with spaces removed).
  • st (string, optional): State or Province (lowercase two-letter code).
  • zp (string, optional): Zip or Postal Code.
  • country (string, optional): Country (lowercase two-letter code).

License

This package is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please submit issues and pull requests on the GitHub repository.

Acknowledgments

This package uses the Facebook Pixel library for tracking and analytics. For more information, visit the Facebook Pixel documentation.