Installing Meta Pixel on Netlify CMS / Decap CMS Sites | OpsBlu Docs

Installing Meta Pixel on Netlify CMS / Decap CMS Sites

Step-by-step guide to implementing Meta Pixel on static sites built with Hugo, Jekyll, Gatsby, Next.js, and 11ty

This guide provides detailed instructions for installing Meta Pixel (Facebook Pixel) on static sites built with Netlify CMS (now Decap CMS) across different static site generators.

Prerequisites

  1. Create Meta Pixel

  2. Have Netlify CMS site using a static site generator

  3. Set up environment variables (recommended):

    • Production Pixel ID
    • Staging/Preview Pixel ID (optional)

Meta Pixel Base Code

Standard Meta Pixel code:

<!-- Meta Pixel Code -->
<script>
  !function(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)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', 'YOUR_PIXEL_ID');
  fbq('track', 'PageView');
</script>
<noscript><img height="1" width="1" style="display:none"
  src="https://www.facebook.com/tr?id=YOUR_PIXEL_ID&ev=PageView&noscript=1"
/></noscript>
<!-- End Meta Pixel Code -->

Method 1: Hugo + Meta Pixel

Step 1: Configure Environment Variables

Add to netlify.toml:

[context.production.environment]
  HUGO_META_PIXEL_ID = "123456789012345"

[context.deploy-preview.environment]
  HUGO_META_PIXEL_ID = "987654321098765"

[context.branch-deploy.environment]
  HUGO_META_PIXEL_ID = "987654321098765"

Step 2: Create Meta Pixel Partial

Create layouts/partials/meta-pixel.html:

{{ with getenv "HUGO_META_PIXEL_ID" }}
<!-- Meta Pixel Code -->
<script>
  !function(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)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');

  fbq('init', '{{ . }}');
  fbq('track', 'PageView');

  {{ if eq $.Type "posts" }}
  // Track blog post views
  fbq('track', 'ViewContent', {
    content_name: '{{ $.Title }}',
    content_category: '{{ $.Section }}',
    content_type: 'article'
  });
  {{ end }}
</script>
<noscript><img height="1" width="1" style="display:none"
  src="https://www.facebook.com/tr?id={{ . }}&ev=PageView&noscript=1"
/></noscript>
<!-- End Meta Pixel Code -->
{{ end }}

Step 3: Include in Base Template

Modify layouts/_default/baseof.html:

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
  <head>
    <meta charset="UTF-8">
    <title>{{ .Title }}</title>
    {{ partial "meta-pixel.html" . }}
  </head>
  <body>
    {{ block "main" . }}{{ end }}
  </body>
</html>

Step 4: Deploy and Verify

git add .
git commit -m "Add Meta Pixel tracking"
git push origin main

Method 2: Jekyll + Meta Pixel

Step 1: Configure Pixel ID

Add to _config.yml:

meta_pixel_id: 123456789012345

# Or environment-specific
production:
  meta_pixel_id: 123456789012345

development:
  meta_pixel_id: 987654321098765

Step 2: Create Meta Pixel Include

Create _includes/meta-pixel.html:

{% if jekyll.environment == "production" %}
  {% if site.meta_pixel_id %}
<!-- Meta Pixel Code -->
<script>
  !function(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)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');

  fbq('init', '{{ site.meta_pixel_id }}');
  fbq('track', 'PageView');

  {% if page.layout == "post" %}
  // Track blog post views
  fbq('track', 'ViewContent', {
    content_name: '{{ page.title | escape }}',
    content_category: '{{ page.categories | first }}',
    content_type: 'article'
  });
  {% endif %}
</script>
<noscript><img height="1" width="1" style="display:none"
  src="https://www.facebook.com/tr?id={{ site.meta_pixel_id }}&ev=PageView&noscript=1"
/></noscript>
<!-- End Meta Pixel Code -->
  {% endif %}
{% endif %}

Step 3: Include in Default Layout

Modify _layouts/default.html:

<!DOCTYPE html>
<html lang="{{ site.lang | default: "en-US" }}">
  <head>
    <meta charset="UTF-8">
    <title>{{ page.title | default: site.title }}</title>
    {% include meta-pixel.html %}
  </head>
  <body>
    {{ content }}
  </body>
</html>

Step 4: Configure Netlify Environment

In netlify.toml:

[build]
  command = "JEKYLL_ENV=production bundle exec jekyll build"
  publish = "_site"

[context.production.environment]
  JEKYLL_ENV = "production"

Method 3: Gatsby + Meta Pixel

Step 1: Install Plugin

npm install gatsby-plugin-facebook-pixel

Step 2: Configure Plugin

Add to gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-facebook-pixel`,
      options: {
        pixelId: process.env.GATSBY_FB_PIXEL_ID || "123456789012345",
      },
    },
  ],
};

Step 3: Set Environment Variables

Create .env.production:

GATSBY_FB_PIXEL_ID=123456789012345

Create .env.development:

GATSBY_FB_PIXEL_ID=987654321098765

Add to Netlify:

Site Settings → Build & Deploy → Environment

GATSBY_FB_PIXEL_ID = 123456789012345

Step 4: Track Custom Events

Create src/utils/fbPixel.js:

export const trackViewContent = (contentName, contentCategory) => {
  if (typeof window !== 'undefined' && window.fbq) {
    window.fbq('track', 'ViewContent', {
      content_name: contentName,
      content_category: contentCategory,
      content_type: 'article'
    });
  }
};

export const trackLead = (formName) => {
  if (typeof window !== 'undefined' && window.fbq) {
    window.fbq('track', 'Lead', {
      content_name: formName
    });
  }
};

export const trackCustom = (eventName, params = {}) => {
  if (typeof window !== 'undefined' && window.fbq) {
    window.fbq('trackCustom', eventName, params);
  }
};

Use in components:

import React, { useEffect } from 'react';
import { trackViewContent } from '../utils/fbPixel';

const BlogPost = ({ data }) => {
  const post = data.markdownRemark;

  useEffect(() => {
    trackViewContent(post.frontmatter.title, post.frontmatter.category);
  }, [post]);

  return (
    <article>
      <h1>{post.frontmatter.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.html }} />
    </article>
  );
};

export default BlogPost;

Step 5: Build and Deploy

gatsby build
git add .
git commit -m "Add Meta Pixel tracking"
git push origin main

Method 4: Next.js + Meta Pixel

Step 1: Create Meta Pixel Component

Create components/MetaPixel.js:

import Script from 'next/script';

const MetaPixel = ({ pixelId }) => {
  if (!pixelId) return null;

  return (
    <>
      <Script
        id="fb-pixel"
        strategy="afterInteractive"
        dangerouslySetInnerHTML={{
          __html: `
            !function(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)}(window, document,'script',
            'https://connect.facebook.net/en_US/fbevents.js');
            fbq('init', '${pixelId}');
            fbq('track', 'PageView');
          `,
        }}
      />
      <noscript>
        <img
          height="1"
          width="1"
          style={{ display: 'none' }}
          src={`https://www.facebook.com/tr?id=${pixelId}&ev=PageView&noscript=1`}
        />
      </noscript>
    </>
  );
};

export default MetaPixel;

Step 2: Add to _app.js

Modify pages/_app.js:

import { useEffect } from 'react';
import { useRouter } from 'next/router';
import MetaPixel from '../components/MetaPixel';

function MyApp({ Component, pageProps }) {
  const router = useRouter();
  const pixelId = process.env.NEXT_PUBLIC_FB_PIXEL_ID;

  useEffect(() => {
    // Track page views on route change
    const handleRouteChange = () => {
      if (typeof window !== 'undefined' && window.fbq) {
        window.fbq('track', 'PageView');
      }
    };

    router.events.on('routeChangeComplete', handleRouteChange);

    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
  }, [router.events]);

  return (
    <>
      {process.env.NODE_ENV === 'production' && <MetaPixel pixelId={pixelId} />}
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Step 3: Create Event Tracking Utilities

Create lib/fbPixel.js:

export const pageview = () => {
  if (typeof window !== 'undefined' && window.fbq) {
    window.fbq('track', 'PageView');
  }
};

export const event = (name, options = {}) => {
  if (typeof window !== 'undefined' && window.fbq) {
    window.fbq('track', name, options);
  }
};

export const customEvent = (name, options = {}) => {
  if (typeof window !== 'undefined' && window.fbq) {
    window.fbq('trackCustom', name, options);
  }
};

// Specific event helpers
export const trackViewContent = (contentName, contentCategory) => {
  event('ViewContent', {
    content_name: contentName,
    content_category: contentCategory,
    content_type: 'article'
  });
};

export const trackLead = (formName) => {
  event('Lead', {
    content_name: formName
  });
};

export const trackSearch = (searchString) => {
  event('Search', {
    search_string: searchString
  });
};

Use in components:

import * as fbPixel from '../lib/fbPixel';

const NewsletterForm = () => {
  const handleSubmit = (e) => {
    e.preventDefault();

    // Track lead
    fbPixel.trackLead('Newsletter Signup');

    // Submit form logic...
  };

  return <form
};

Step 4: Environment Variables

Create .env.local:

NEXT_PUBLIC_FB_PIXEL_ID=123456789012345

Add to netlify.toml:

[context.production.environment]
  NEXT_PUBLIC_FB_PIXEL_ID = "123456789012345"

[context.deploy-preview.environment]
  NEXT_PUBLIC_FB_PIXEL_ID = "987654321098765"

Method 5: 11ty (Eleventy) + Meta Pixel

Step 1: Create Data File

Create _data/metaPixel.js:

module.exports = {
  id: process.env.META_PIXEL_ID || "123456789012345"
};

Step 2: Create Meta Pixel Include

Create _includes/meta-pixel.njk:

{% if metaPixel.id %}
<!-- Meta Pixel Code -->
<script>
  !function(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)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');

  fbq('init', '{{ metaPixel.id }}');
  fbq('track', 'PageView');

  {% if layout == "post" %}
  // Track blog post views
  fbq('track', 'ViewContent', {
    content_name: '{{ title }}',
    content_category: '{{ category }}',
    content_type: 'article'
  });
  {% endif %}
</script>
<noscript><img height="1" width="1" style="display:none"
  src="https://www.facebook.com/tr?id={{ metaPixel.id }}&ev=PageView&noscript=1"
/></noscript>
<!-- End Meta Pixel Code -->
{% endif %}

Step 3: Include in Base Layout

Modify _includes/layouts/base.njk:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>{{ title }}</title>
    {% include "meta-pixel.njk" %}
  </head>
  <body>
    {{ content | safe }}
  </body>
</html>

Step 4: Configure Environment

Add to netlify.toml:

[build]
  command = "npm run build"
  publish = "_site"

[build.environment]
  META_PIXEL_ID = "123456789012345"

[context.deploy-preview.environment]
  META_PIXEL_ID = "987654321098765"

Verification Steps

1. Install Meta Pixel Helper

Install Meta Pixel Helper Chrome Extension

2. Check Pixel Fires

  1. Visit your deployed site
  2. Click Meta Pixel Helper icon
  3. Verify pixel shows as "Active"
  4. Check for PageView event
  5. Look for warnings or errors

3. Use Test Events

  1. Open Meta Events Manager
  2. Click Test Events tab
  3. Enter your site URL
  4. Visit site with ?fbclid=test parameter
  5. Verify events appear in Test Events

4. Browser Console Check

// Check if fbq is loaded
console.log(typeof fbq); // Should be 'function'

// Manually fire test event
fbq('trackCustom', 'TestEvent', { test: true });

// Check pixel queue
console.log(fbq.queue);

Common Setup Issues

Pixel Not Loading on Localhost

Issue: Meta Pixel doesn't load during local development.

Solution: Intentional. Test on preview deploys or temporarily enable:

// For testing only - remove before committing
if (process.env.NODE_ENV === 'development') {
  fbq('init', 'YOUR_PIXEL_ID');
}

Multiple PageView Events

Issue: SPA frameworks send duplicate PageView events.

Solution: Don't call fbq('track', 'PageView') on route changes if already in base code:

// pages/_app.js - Next.js example
router.events.on('routeChangeComplete', () => {
  // Pixel plugin handles PageView automatically
  // Only track custom events here
});

Preview Deploys Polluting Production Data

Issue: Preview URLs send events to production pixel.

Solution: Use environment-specific pixel IDs:

[context.production.environment]
  PIXEL_ID = "123456789012345"

[context.deploy-preview.environment]
  PIXEL_ID = "987654321098765"

Ad Blockers Blocking Pixel

Issue: Pixel doesn't load due to ad blockers.

Solution: This is expected user behavior. For critical tracking, implement Conversion API (CAPI) server-side.

Next Steps

शीर्ष पर वापस जाएँ