0.2.0 • Published 5 months ago

next-facebook-tracking v0.2.0

Weekly downloads
-
License
MIT
Repository
-
Last release
5 months ago

next-facebook-tracking

next-facebook-tracking is a simple and efficient library for integrating Facebook Pixel and Conversions API tracking into your Next.js application. It provides easy-to-use components and hooks to handle various Facebook Pixel events.

Installation

Install the package via npm or yarn:

npm i --save next-facebook-tracking

Usage

Setup

First, create a Facebook tracking instance:

// facebook.ts
import {FacebookTracking} from 'next-facebook-tracking'

export const facebook = new FacebookTracking({
  // pixelId: process.env.NEXT_PUBLIC_FACEBOOK_PIXEL,
  // accessToken: process.env.FACEBOOK_CONVERSIONS_API_TOKEN,
  debug: true,
})

Add the Provider to Your Layout

Wrap your application's layout with the FacebookTrackingProvider in layout.tsx:

// layout.tsx
import {
  FacebookTrackingProvider,
  FacebookPageView,
} from 'next-facebook-tracking/components'
import {facebook} from './facebook'

export default function RootLayout({children}) {
  return (
    <html lang="en">
      <body>
        <FacebookTrackingProvider client={facebook}>
          {children}
          <FacebookPageView
            action={async event => {
              'use server'
              facebook.track(event)
            }}
          />
        </FacebookTrackingProvider>
      </body>
    </html>
  )
}

Create a Custom Script

FacebookTrackingProvider will load try to load Facebook's Pixel script from /scripts/pixel.js after the first render so you need to create this file:

// public/scripts/pixel.js
const PIXEL_ID = document.currentScript.getAttribute('data-pixel-id')

function initializeFacebookPixel(f, b, e, v, n, t, s) {
  if (f.fbq) return
  n = f.fbq = function () {
    n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments)
  }
  if (!f._fbq) f._fbq = n
  n.push = n
  n.loaded = !0
  n.version = '2.0'
  n.queue = []
  t = b.createElement(e)
  t.async = !0
  t.src = v
  s = b.getElementsByTagName(e)[0]
  s.parentNode.insertBefore(t, s)
}

initializeFacebookPixel(
  window,
  document,
  'script',
  'https://connect.facebook.net/en_US/fbevents.js',
)

window.fbq('init', PIXEL_ID)

Track Events on Page Load and Interactions

Use the facebook instance to track events on page load and interactions in page.tsx:

// page.tsx
import {facebook} from './facebook'
import {
  FacebookTrackOnClick,
  FacebookTrackOnRender,
} from 'next-facebook-tracking/components'

export default async function Home() {
  // This will run on the server
  await facebook.track({
    event_name: 'PageView',
  })

  return (
    <>
      <FacebookTrackOnClick
        action={async event => {
          'use server'
          facebook.track(event)
        }}
        event={{
          event_name: 'AddToCart',
          custom_data: {
            value: 10.1,
            currency: 'USD',
            num_items: 1,
          },
        }}
      >
        <button>Track something</button>
      </FacebookTrackOnClick>

      <FacebookTrackOnRender
        event={{
          event_name: 'InitiateCheckout',
          custom_data: {
            value: 30.1,
            currency: 'USD',
            num_items: 3,
          },
        }}
      />
    </>
  )
}

FacebookTracking Class

Configuration

The FacebookTracking class is used to manage Facebook Pixel and Conversions API tracking.

Constructor

new FacebookTracking(config: FacebookTrackingConfig)

FacebookTrackingConfig Options:

  • pixelId (string): The Facebook pixel ID. Defaults to NEXT_PUBLIC_FACEBOOK_PIXEL env var.
  • accessToken (string): The access token for Facebook Conversions API (optional). Defaults to FACEBOOK_CONVERSIONS_API_TOKEN env var.
  • testCode (string): The test code for Facebook Conversions API (optional). Defaults to FACEBOOK_TEST_EVENT_CODE env var.
  • debug (boolean): Enable or disable debug mode. Defaults to false.

Methods

track

Tracks custom events.

async track<T extends Facebook.Event.EventName>(event: Facebook.Event.EventData<T>)

Custom Hook

useFacebookPixel

Provides access to the FacebookPixel context.

const context = useFacebookPixel()

Components

FacebookTrackingProvider

A context provider for the Facebook tracking instance.

Props:

  • client (FacebookTracking): The Facebook tracking instance.

FacebookPageView

Tracks page views.

FacebookTrackOnClick

Tracks events when a component is clicked.

Props:

  • action (function): The function to execute on click.
  • event (object): The event details to track.

FacebookTrackOnRender

Tracks events when a component is rendered.

Props:

  • event (object): The event details to track.

License

MIT License


Feel free to customize this README file further to match any additional features or details specific to your package.

0.1.13

5 months ago

0.2.0

5 months ago

0.1.10

11 months ago

0.1.11

11 months ago

0.1.12

9 months ago

0.1.9

11 months ago

0.1.8

11 months ago

0.1.7-alpha.8

11 months ago

0.1.7-alpha.7

11 months ago

0.1.7-alpha.6

11 months ago

0.1.7-alpha.5

11 months ago

0.1.7-alpha.4

11 months ago

0.1.7-alpha.3

11 months ago

0.1.7-alpha.1

11 months ago

0.1.7-alpha.0

11 months ago

0.1.6

11 months ago

0.1.5

11 months ago

0.1.4

11 months ago

0.1.3

11 months ago

0.1.2

12 months ago

0.1.1

12 months ago

0.1.0

12 months ago