Meta Pixel Setup

Install and configure Meta Pixel for Facebook and Instagram ad tracking on OSCommerce

Overview

Meta Pixel (formerly Facebook Pixel) enables:

Facebook & Instagram ad tracking - Measure ad performance
Conversion tracking - Track purchases, leads, and key actions
Retargeting audiences - Build custom audiences
Lookalike audiences - Find new customers similar to existing ones
Dynamic product ads - Show products users viewed

Prerequisites

Facebook Business Account - Create account
Meta Pixel created - Events Manager > Pixels > Create Pixel
Pixel ID - 15-16 digit number
FTP access - To modify OSCommerce files
Backup - Complete site backup

Step 1: Get Your Pixel ID

Go to Facebook Events Manager
Click Data Sources > Pixels
Copy your Pixel ID (e.g., 123456789012345)

Step 2: Install Base Pixel Code

OSCommerce 2.3.x Installation

File: catalog/includes/header.php

Add before closing </head> tag:

<!-- 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', '123456789012345');  // Replace with your Pixel ID
fbq('track', 'PageView');
</script>
<noscript>
  <img height="1" width="1" style="display:none"
       src="https://www.facebook.com/tr?id=123456789012345&ev=PageView&noscript=1"/>
</noscript>
<!-- End Meta Pixel Code -->
</head>

Replace 123456789012345 with your actual Pixel ID.

OSCommerce 2.4.x Installation

File: catalog/includes/modules/header_tags/ht_meta_pixel.php

Create new module:

<?php
class ht_meta_pixel {
  var $code = 'ht_meta_pixel';
  var $group = 'header_tags';
  var $title;
  var $description;
  var $sort_order;
  var $enabled = false;

  function __construct() {
    $this->title = 'Meta Pixel';
    $this->description = 'Add Meta Pixel tracking for Facebook & Instagram ads';
    $this->sort_order = 200;
    $this->enabled = (defined('MODULE_HEADER_TAGS_META_PIXEL_STATUS') && MODULE_HEADER_TAGS_META_PIXEL_STATUS == 'True');
  }

  function execute() {
    global $oscTemplate;

    if ($this->enabled) {
      $pixel_id = MODULE_HEADER_TAGS_META_PIXEL_ID;

      $pixel_code = <<<EOD
<!-- 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', '{$pixel_id}');
fbq('track', 'PageView');
</script>
<noscript>
  <img height="1" width="1" style="display:none"
       src="https://www.facebook.com/tr?id={$pixel_id}&ev=PageView&noscript=1"/>
</noscript>
<!-- End Meta Pixel Code -->
EOD;

      $oscTemplate->addContent($pixel_code, $this->group);
    }
  }

  function isEnabled() {
    return $this->enabled;
  }

  function check() {
    return defined('MODULE_HEADER_TAGS_META_PIXEL_STATUS');
  }

  function install() {
    tep_db_query("INSERT INTO configuration (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) VALUES ('Enable Meta Pixel', 'MODULE_HEADER_TAGS_META_PIXEL_STATUS', 'True', 'Enable Meta Pixel tracking?', '6', '1', 'tep_cfg_select_option(array(\'True\', \'False\'), ', now())");
    tep_db_query("INSERT INTO configuration (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, date_added) VALUES ('Meta Pixel ID', 'MODULE_HEADER_TAGS_META_PIXEL_ID', '', 'Enter your Meta Pixel ID (15-16 digits)', '6', '2', now())");
  }

  function remove() {
    tep_db_query("DELETE FROM configuration WHERE configuration_key IN ('" . implode("', '", $this->keys()) . "')");
  }

  function keys() {
    return array('MODULE_HEADER_TAGS_META_PIXEL_STATUS', 'MODULE_HEADER_TAGS_META_PIXEL_ID');
  }
}
?>

Install via admin:

Admin > Modules > Header Tags > Install Module > Meta Pixel

Installation via GTM (Recommended)

If you have GTM installed:

GTM > Tags > New
Tag Configuration > Custom HTML
Paste Meta Pixel code
Triggering > All Pages
Save and Publish

Step 3: Verify Installation

Method 1: Meta Pixel Helper

Install Meta Pixel Helper
Visit your store
Click extension icon
Should show: Pixel Found with your Pixel ID
PageView event should be listed

Method 2: Test Events Tool

Go to Events Manager > Test Events
Enter your store URL OR use browser extension
Click Open Website
Visit pages and see events appear instantly

Method 3: Browser Console

// Open console (F12) and type:
typeof fbq
// Should return "function"

_fbq.instance.pixelsByID
// Should show your Pixel ID

Method 4: Network Tab

F12 > Network > Filter: "facebook"

Should see requests to:

connect.facebook.net/en_US/fbevents.js
facebook.com/tr?id=YOUR_PIXEL_ID

Step 4: Configure Advanced Matching

Enhanced data matching improves attribution and audience building.

File: catalog/includes/header.php

<?php
// Get customer data if logged in
$customer_email = null;
$customer_phone = null;
$customer_firstname = null;
$customer_lastname = null;
$customer_city = null;
$customer_state = null;
$customer_zip = null;
$customer_country = null;

if (tep_session_is_registered('customer_id')) {
  $customer_query = tep_db_query("SELECT * FROM " . TABLE_CUSTOMERS . " WHERE customers_id = '" . (int)$customer_id . "'");
  $customer = tep_db_fetch_array($customer_query);

  if ($customer) {
    $customer_email = strtolower($customer['customers_email_address']);
    $customer_phone = preg_replace('/[^0-9]/', '', $customer['customers_telephone']);
    $customer_firstname = strtolower($customer['customers_firstname']);
    $customer_lastname = strtolower($customer['customers_lastname']);

    // Get address
    $address_query = tep_db_query("SELECT * FROM " . TABLE_ADDRESS_BOOK . " WHERE customers_id = '" . (int)$customer_id . "' AND address_book_id = '" . (int)$customer['customers_default_address_id'] . "'");
    $address = tep_db_fetch_array($address_query);

    if ($address) {
      $customer_city = strtolower($address['entry_city']);
      $customer_state = strtolower($address['entry_state']);
      $customer_zip = preg_replace('/[^0-9]/', '', $address['entry_postcode']);

      $country_query = tep_db_query("SELECT countries_iso_code_2 FROM " . TABLE_COUNTRIES . " WHERE countries_id = '" . (int)$address['entry_country_id'] . "'");
      $country = tep_db_fetch_array($country_query);
      $customer_country = $country ? strtolower($country['countries_iso_code_2']) : null;
    }
  }
}
?>

<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', '123456789012345', {
  <?php if ($customer_email): ?>
  em: '<?php echo $customer_email; ?>',
  <?php endif; ?>
  <?php if ($customer_phone): ?>
  ph: '<?php echo $customer_phone; ?>',
  <?php endif; ?>
  <?php if ($customer_firstname): ?>
  fn: '<?php echo $customer_firstname; ?>',
  <?php endif; ?>
  <?php if ($customer_lastname): ?>
  ln: '<?php echo $customer_lastname; ?>',
  <?php endif; ?>
  <?php if ($customer_city): ?>
  ct: '<?php echo $customer_city; ?>',
  <?php endif; ?>
  <?php if ($customer_state): ?>
  st: '<?php echo $customer_state; ?>',
  <?php endif; ?>
  <?php if ($customer_zip): ?>
  zp: '<?php echo $customer_zip; ?>',
  <?php endif; ?>
  <?php if ($customer_country): ?>
  country: '<?php echo $customer_country; ?>'
  <?php endif; ?>
});

fbq('track', 'PageView');
</script>

Step 5: Configure Event Tracking

See Meta Pixel Event Tracking for detailed event implementation.

Basic Events to Implement

Add these events for complete ecommerce tracking:

ViewContent - Product page views
AddToCart - Items added to cart
InitiateCheckout - Checkout started
Purchase - Completed transactions

Privacy & Compliance

If serving EU customers, obtain consent before loading Pixel:

<?php
// Check if user has consented
$has_consent = isset($_COOKIE['cookie_consent']) && $_COOKIE['cookie_consent'] == 'accepted';

if ($has_consent || !$is_eu_visitor) {
?>
<!-- Meta Pixel Code -->
<script>
  // Pixel code here
</script>
<?php
}
?>

Disable Automatic Advanced Matching

If you can't guarantee GDPR compliance:

fbq('init', '123456789012345', {
  autoConfig: false,  // Disable automatic advanced matching
  external_id: ''     // Optional: use hashed customer ID
});

Limited Data Use (California Privacy)

For California customers (CCPA):

fbq('dataProcessingOptions', ['LDU'], 1, 1000);  // Enable Limited Data Use
fbq('init', '123456789012345');
fbq('track', 'PageView');

Multiple Pixels

Track to multiple pixels if needed:

// Initialize multiple pixels
fbq('init', '111111111111111');  // Main pixel
fbq('init', '222222222222222');  // Agency pixel

// Track to all pixels
fbq('track', 'PageView');

// Track to specific pixel only
fbq('trackSingle', '111111111111111', 'Purchase', {
  value: 49.99,
  currency: 'USD'
});

Conversions API (Server-Side)

For improved accuracy and iOS 14+ tracking, implement Conversions API.

File: catalog/checkout_process.php

<?php
// After order is created
if ($insert_id) {
  // Get order details
  $order_query = tep_db_query("SELECT * FROM " . TABLE_ORDERS . " WHERE orders_id = '" . (int)$insert_id . "'");
  $order = tep_db_fetch_array($order_query);

  // Prepare Conversions API data
  $access_token = 'YOUR_CONVERSIONS_API_ACCESS_TOKEN';
  $pixel_id = '123456789012345';

  $data = array(
    'data' => array(
      array(
        'event_name' => 'Purchase',
        'event_time' => time(),
        'action_source' => 'website',
        'event_source_url' => 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
        'user_data' => array(
          'em' => array(hash('sha256', strtolower($order['customers_email_address']))),
          'ph' => array(hash('sha256', preg_replace('/[^0-9]/', '', $order['customers_telephone']))),
          'client_ip_address' => $_SERVER['REMOTE_ADDR'],
          'client_user_agent' => $_SERVER['HTTP_USER_AGENT'],
          'fbc' => isset($_COOKIE['_fbc']) ? $_COOKIE['_fbc'] : null,
          'fbp' => isset($_COOKIE['_fbp']) ? $_COOKIE['_fbp'] : null
        ),
        'custom_data' => array(
          'value' => $order['order_total'],
          'currency' => $order['currency'],
          'content_type' => 'product'
        )
      )
    )
  );

  // Send to Conversions API
  $url = "https://graph.facebook.com/v18.0/{$pixel_id}/events?access_token={$access_token}";

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $result = curl_exec($ch);
  curl_close($ch);
}
?>

Testing Checklist

Pixel code appears in page source
Pixel ID is correct
Meta Pixel Helper shows pixel active
PageView events appear in Test Events
No JavaScript errors in console
Advanced matching data populated (if enabled)
Pixel fires on all pages
GDPR consent implemented (if required)

Common Issues

Issue 1: Pixel Not Loading

Problem: Pixel Helper shows "No Pixel Found"

Solutions:

Check Pixel ID is correct (15-16 digits)
Verify code is in header.php, not footer
Clear browser cache
Check for JavaScript errors
Verify file was saved properly

Issue 2: Blocked by Ad Blockers

Problem: Pixel doesn't load for some users

Solutions:

This is normal - many users block tracking
Implement Conversions API for server-side backup
Use first-party cookies
No workaround for client-side blocking

Issue 3: Multiple Pixels Firing

Problem: Same Pixel ID fires twice

Solutions:

Check header.php and footer.php
Search all files for Pixel ID
Check GTM for duplicate tags
Remove one instance

Issue 4: Advanced Matching Not Working

Problem: User data not showing in Events Manager

Solutions:

Verify data is properly hashed (SHA-256)
Use lowercase for email
Remove spaces from phone numbers
Check customer data exists in database

Best Practices

1. Load Pixel Early

Place in <head> section, as high as possible for better tracking.

2. Use Standard Events

Prefer standard events (Purchase, AddToCart) over custom events for better optimization.

3. Implement Server-Side Tracking

Conversions API provides backup when browser tracking fails.

4. Test Before Launch

Always test with Test Events tool before running ads.

5. Monitor Data Quality

Check Events Manager regularly for:

Event match quality
Advanced matching rate
Deduplication status

Next Steps

Additional Resources

返回顶部

Meta Pixel Setup

Overview

Prerequisites

Step 1: Get Your Pixel ID

Step 2: Install Base Pixel Code

OSCommerce 2.3.x Installation

OSCommerce 2.4.x Installation

Installation via GTM (Recommended)

Step 3: Verify Installation

Method 1: Meta Pixel Helper

Method 2: Test Events Tool

Method 3: Browser Console

Method 4: Network Tab

Step 4: Configure Advanced Matching

Step 5: Configure Event Tracking

Basic Events to Implement

Privacy & Compliance

GDPR Compliance

Disable Automatic Advanced Matching

Limited Data Use (California Privacy)

Multiple Pixels

Conversions API (Server-Side)

Testing Checklist

Common Issues

Issue 1: Pixel Not Loading

Issue 2: Blocked by Ad Blockers

Issue 3: Multiple Pixels Firing

Issue 4: Advanced Matching Not Working

Best Practices

1. Load Pixel Early

2. Use Standard Events

3. Implement Server-Side Tracking

4. Test Before Launch

5. Monitor Data Quality

Next Steps

Additional Resources