Meta Pixel Setup on Kentico (Step-by-Step) | OpsBlu Docs

Meta Pixel Setup on Kentico (Step-by-Step)

Step-by-step guide to installing Facebook Pixel (Meta Pixel) on Kentico Xperience websites

This guide covers how to install and configure Meta Pixel (formerly Facebook Pixel) on Kentico Xperience websites for tracking conversions, optimizing ads, and building audiences.

Prerequisites

  • Facebook Business Manager account
  • Meta Pixel ID (format: 15-16 digit number)
  • Admin access to Kentico
  • Access to edit layout files or master pages

What is Meta Pixel?

Meta Pixel is a JavaScript code that tracks visitor actions on your website, enabling you to:

  • Measure ad campaign effectiveness
  • Optimize ad delivery
  • Build custom audiences for remarketing
  • Track conversions from Facebook/Instagram ads

Method 1: Direct Implementation

For MVC Development Model (Kentico 12+)

  1. Locate Your Layout File

Navigate to ~/Views/Shared/_Layout.cshtml or your custom layout file.

  1. Add Meta Pixel Base Code

Add this code in the <head> section:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>@ViewBag.Title</title>

    <!-- 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 -->
</head>
<body>
    @RenderBody()
</body>
</html>
  1. Make It Dynamic with Kentico Settings

Create Setting in Kentico:

  • Go to Settings → Integration → Social Media
  • Create new setting key: FacebookPixelID
  • Enter your Meta Pixel ID

Update Layout File:

@using CMS.Helpers
@using CMS.SiteProvider
@{
    var pixelId = SettingsKeyInfoProvider.GetValue("FacebookPixelID", SiteContext.CurrentSiteID);
}

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>@ViewBag.Title</title>

    @if (!string.IsNullOrEmpty(pixelId))
    {
        <!-- 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', '@pixelId');
          fbq('track', 'PageView');
        </script>
        <noscript>
          <img height="1" width="1" style="display:none"
               src="https://www.facebook.com/tr?id=@pixelId&ev=PageView&noscript=1"/>
        </noscript>
        <!-- End Meta Pixel Code -->
    }
</head>
<body>
    @RenderBody()
</body>
</html>

For Portal Engine (Legacy)

  1. Access Master Page

    • Go to Design → Master pages
    • Edit your root master page

  2. Add Pixel Code to Master Page

In the <head> section:

<head runat="server">
    <!-- 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 -->
</head>
  1. Using Kentico Macros
{% raw %}{%
var pixelId = SettingsKeyInfoProvider.GetValue("FacebookPixelID");
if (!String.IsNullOrEmpty(pixelId)) {
%}
<!-- 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', '{% pixelId %}');
  fbq('track', 'PageView');
</script>
<noscript>
  <img height="1" width="1" style="display:none"
       src="https://www.facebook.com/tr?id={% pixelId %}&ev=PageView&noscript=1"/>
</noscript>
<!-- End Meta Pixel Code -->
{% } %}{% endraw %}

Using GTM provides better control and doesn't require code changes:

  1. Prerequisites

  2. Create Meta Pixel Tag in GTM

    • In GTM, go to Tags → New
    • Click Tag Configuration
    • Choose Custom HTML

  3. Add 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>

  1. Set Trigger

    • Click Triggering
    • Select All Pages

  2. Save and Publish

    • Name: "Meta Pixel - Base Code"
    • Save tag
    • Submit and publish container

Method 3: Custom Web Part (Portal Engine)

Create a reusable web part:

  1. Create Web Part

    • Go to Development → Web parts → New web part
    • Name: MetaPixel
    • Category: "Analytics"

  2. Web Part Properties

Add these properties:

  • PixelID (Text) - Meta Pixel ID
  • TrackPageView (Boolean) - Track automatic page views
  • EnableAdvancedMatching (Boolean) - Enable advanced matching
  1. Web Part Code (ASCX)
<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="MetaPixel.ascx.cs" Inherits="CustomWebParts.MetaPixel" %>

<% if (!String.IsNullOrEmpty(PixelID)) { %>
<!-- 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');

  <% if (EnableAdvancedMatching) { %>
  fbq('init', '<%= PixelID %>', {
    em: '<%= GetUserEmail() %>',
    fn: '<%= GetUserFirstName() %>',
    ln: '<%= GetUserLastName() %>'
  });
  <% } else { %>
  fbq('init', '<%= PixelID %>');
  <% } %>

  <% if (TrackPageView) { %>
  fbq('track', 'PageView');
  <% } %>
</script>
<noscript>
  <img height="1" width="1" style="display:none"
       src="https://www.facebook.com/tr?id=<%= PixelID %>&ev=PageView&noscript=1"/>
</noscript>
<!-- End Meta Pixel Code -->
<% } %>
  1. Code-Behind (ASCX.CS)
using System;
using CMS.Membership;
using CMS.Helpers;

public partial class CMSWebParts_Analytics_MetaPixel : CMSAbstractWebPart
{
    public string PixelID { get; set; }
    public bool TrackPageView { get; set; } = true;
    public bool EnableAdvancedMatching { get; set; } = false;

    protected string GetUserEmail()
    {
        if (!EnableAdvancedMatching) return "";

        var user = MembershipContext.AuthenticatedUser;
        if (user != null && !user.IsPublic())
        {
            return SecurityHelper.GetSHA256Hash(user.Email);
        }
        return "";
    }

    protected string GetUserFirstName()
    {
        if (!EnableAdvancedMatching) return "";

        var user = MembershipContext.AuthenticatedUser;
        if (user != null && !user.IsPublic())
        {
            return SecurityHelper.GetSHA256Hash(user.FirstName);
        }
        return "";
    }

    protected string GetUserLastName()
    {
        if (!EnableAdvancedMatching) return "";

        var user = MembershipContext.AuthenticatedUser;
        if (user != null && !user.IsPublic())
        {
            return SecurityHelper.GetSHA256Hash(user.LastName);
        }
        return "";
    }
}

Advanced Matching (Enhanced Tracking)

Advanced matching improves attribution by automatically hashing and sending user data:

@using CMS.Membership
@using CMS.Helpers
@{
    var user = MembershipContext.AuthenticatedUser;
    var pixelId = SettingsKeyInfoProvider.GetValue("FacebookPixelID", SiteContext.CurrentSiteID);

    string userEmail = "";
    string userFirstName = "";
    string userLastName = "";

    if (user != null && !user.IsPublic())
    {
        // Hash user data for privacy
        userEmail = SecurityHelper.GetSHA256Hash(user.Email.ToLower().Trim());
        userFirstName = SecurityHelper.GetSHA256Hash(user.FirstName.ToLower().Trim());
        userLastName = SecurityHelper.GetSHA256Hash(user.LastName.ToLower().Trim());
    }
}

<script>
  fbq('init', '@pixelId', {
    em: '@userEmail',
    fn: '@userFirstName',
    ln: '@userLastName'
  });
  fbq('track', 'PageView');
</script>

Multi-Site Configuration

For multiple sites with different pixels:

@using CMS.SiteProvider
@{
    var currentSite = SiteContext.CurrentSite;
    var pixelId = SettingsKeyInfoProvider.GetValue("FacebookPixelID", currentSite.SiteID);
}

@if (!string.IsNullOrEmpty(pixelId))
{
    <!-- Meta Pixel for @currentSite.SiteName -->
    <script>
      fbq('init', '@pixelId');
      fbq('track', 'PageView');
    </script>
}

Multiple Pixels on One Site

If you need to track with multiple pixels:

@{
    var primaryPixel = SettingsKeyInfoProvider.GetValue("FacebookPixelID", SiteContext.CurrentSiteID);
    var secondaryPixel = SettingsKeyInfoProvider.GetValue("FacebookPixelID_Secondary", SiteContext.CurrentSiteID);
}

<script>
  // Initialize first pixel
  fbq('init', '@primaryPixel');

  @if (!string.IsNullOrEmpty(secondaryPixel))
  {
    <text>
    // Initialize second pixel
    fbq('init', '@secondaryPixel');
    </text>
  }

  // Track page view for all pixels
  fbq('track', 'PageView');
</script>

Environment-Based Loading

Prevent pixel from firing in non-production:

@{
    var isProduction = SiteContext.CurrentSite.SiteName == "ProductionSite";
    var pixelId = SettingsKeyInfoProvider.GetValue("FacebookPixelID", SiteContext.CurrentSiteID);
}

@if (isProduction && !string.IsNullOrEmpty(pixelId))
{
    <!-- Meta Pixel Code -->
}

Or use a setting:

@{
    var enablePixel = SettingsKeyInfoProvider.GetBoolValue("EnableFacebookPixel", SiteContext.CurrentSiteID);
    var pixelId = SettingsKeyInfoProvider.GetValue("FacebookPixelID", SiteContext.CurrentSiteID);
}

@if (enablePixel && !string.IsNullOrEmpty(pixelId))
{
    <!-- Meta Pixel Code -->
}

Respect user privacy with consent management:

With OneTrust

<script type="text/plain" class="optanon-category-C0004">
  // Meta Pixel code here
  // Will only load if user accepts advertising cookies
  fbq('init', 'YOUR_PIXEL_ID');
  fbq('track', 'PageView');
</script>

With Cookiebot

<script data-cookieconsent="marketing">
  // Meta Pixel code here
  fbq('init', 'YOUR_PIXEL_ID');
  fbq('track', 'PageView');
</script>

<script>
  // Check if user has consented to marketing cookies
  function hasMarketingConsent() {
    // Your consent checking logic
    return localStorage.getItem('marketingConsent') === 'true';
  }

  if (hasMarketingConsent()) {
    !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');
  }
</script>

Testing Your Implementation

1. Meta Pixel Helper (Chrome Extension)

  1. Install Meta Pixel Helper
  2. Navigate to your Kentico site
  3. Click the extension icon
  4. Verify:
    • Pixel found
    • Pixel ID is correct
    • PageView event fires
    • No errors shown

2. Facebook Events Manager

  1. Open Facebook Business Manager
  2. Go to Events Manager
  3. Select your pixel
  4. Click Test Events
  5. Enter your website URL
  6. Navigate your site and verify events appear in real-time

3. Browser Developer Tools

Open console and check:

// Check if fbq is defined
console.log(typeof fbq);  // Should output "function"

// Manually trigger test event
fbq('track', 'PageView');

// Check for pixel in network requests
// Filter Network tab by "facebook"

4. View Pixel Events in Console

// Override fbq to log all events
(function() {
  var originalFbq = window.fbq;
  window.fbq = function() {
    console.log('Meta Pixel Event:', arguments);
    return originalFbq.apply(this, arguments);
  };
})();

Verify Data Receiving in Meta

  1. Go to Events Manager
  2. Select your pixel
  3. View Overview tab
  4. Check for:
    • Active pixel (green indicator)
    • Page views being received
    • Recent event activity

Common Issues

Pixel Not Loading

Check:

  • Pixel ID is correct (15-16 digits)
  • No JavaScript errors in console
  • Code is in <head> section
  • Not blocked by ad blockers

Events Not Tracking

Debug:

  • Check Meta Pixel Helper for errors
  • Verify fbq function is available
  • Check network tab for requests to facebook.com
  • Ensure events fire after pixel initialization

Duplicate Page Views

Causes:

  • Pixel code appears multiple times
  • Both direct implementation and GTM
  • Multiple layout files loading pixel

Fix:

  • Search codebase for fbq('init'
  • Ensure single implementation method
  • Check for duplicate GTM tags

Security Considerations

Content Security Policy (CSP)

If using CSP headers, allow Meta domains:

Content-Security-Policy:
  script-src 'self' 'unsafe-inline' https://connect.facebook.net;
  img-src 'self' https://www.facebook.com;
  connect-src 'self' https://www.facebook.com;

Hash User Data

Always hash personal information:

using CMS.Helpers;

var hashedEmail = SecurityHelper.GetSHA256Hash(user.Email.ToLower().Trim());

Best Practices

  1. Use GTM When Possible: Easier management without code deployments
  2. Implement Consent Management: Respect user privacy
  3. Test Before Production: Use Meta Pixel Helper and Test Events
  4. Use Advanced Matching: Improve attribution with hashed user data
  5. Monitor Pixel Health: Check Events Manager regularly
  6. Document Pixel IDs: Keep record of which pixels are used where
  7. Avoid PII: Never send unhashed personal information
  8. Single Implementation: Choose one method (direct or GTM), not both

Performance Impact

Meta Pixel is lightweight but consider:

  • Loads asynchronously by default
  • ~25KB JavaScript file
  • Additional network requests per event
  • Minimal impact on Core Web Vitals

To further optimize:

// Delay pixel load until user interaction
var pixelLoaded = false;
document.addEventListener('scroll', loadPixel, { once: true });
document.addEventListener('click', loadPixel, { once: true });

function loadPixel() {
  if (pixelLoaded) return;
  // Load Meta Pixel code here
  pixelLoaded = true;
}

Next Steps

Additional Resources

Nach oben