Command Queue

The Pixel Manager Command Queue is a powerful asynchronous API that allows developers to safely execute code and interact with the Pixel Manager, regardless of when the Pixel Manager scripts are loaded on the page.

Available Since

Version 1.49.0 of the Pixel Manager

Why Use the Command Queue?

Modern websites often use optimization techniques like script deferral, lazy loading, or JavaScript bundlers that can delay when scripts are loaded and executed. This creates a timing challenge: your custom code might try to access Pixel Manager functions before they're available, causing errors.

The Command Queue solves this problem by:

• Ensuring execution - Commands are guaranteed to run, whether the Pixel Manager is already loaded or loads later
• Maintaining order - Commands execute in the order they were added to the queue
• Preventing errors - No "undefined" errors from accessing functions before they exist
• Non-blocking - Runs asynchronously without blocking page rendering

How It Works

The Command Queue is a JavaScript array (window._pmwq) that stores functions to be executed. When you add a function to the queue:

1. If Pixel Manager is loaded: The function executes immediately
2. If Pixel Manager is not loaded yet: The function is stored and executes automatically once Pixel Manager loads

Basic Usage

Single Command

window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    // Your code here runs when Pixel Manager is ready
    console.log('Pixel Manager is ready!');
});

Multiple Commands

window._pmwq = window._pmwq || [];

window._pmwq.push(function () {
    console.log('First command');
});

window._pmwq.push(function () {
    console.log('Second command');
});

window._pmwq.push(function () {
    console.log('Third command');
});

Commands execute in the order they were added (First → Second → Third).

Common Use Cases

1. Using Event Filters

Event filters allow you to modify tracking data before it's sent to advertising platforms. The Command Queue ensures your filters are registered at the right time:

window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    // Add a filter to modify purchase data
    pmw.hooks.addFilter('pmw_event_data', 'my-custom-filter', function(eventData) {
        // Add 10% to conversion value
        if (eventData.event_name === 'purchase') {
            eventData.value = eventData.value * 1.1;
        }
        return eventData;
    });
});

2. Accessing Pixel Manager Functions

window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    // Track a custom Facebook event
    pmw.trackCustomFacebookEvent('CustomEvent', {
        custom_param: 'value',
        another_param: 123
    });
});

3. Listening to Pixel Manager Events

window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    // Listen for add-to-cart events
    jQuery(document).on('pmw:add-to-cart', function(event, product) {
        console.log('Product added to cart:', product.name);
        
        // Send custom tracking
        dataLayer.push({
            event: 'custom_add_to_cart',
            product_name: product.name,
            product_price: product.price
        });
    });
});

4. Conditional Tracking

window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    // Only track for specific user roles
    if (pmwDataLayer.user && pmwDataLayer.user.role === 'customer') {
        pmw.hooks.addFilter('pmw_event_data', 'customer-only', function(eventData) {
            eventData.custom_property = 'customer_value';
            return eventData;
        });
    }
});

Using in WordPress (PHP)

You can add Command Queue code through your theme's functions.php or a custom plugin:

Example: Add Custom Event Tracking

/wp-content/themes/child-theme/functions.php

add_action('wp_footer', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            // Track contact form button clicks
            jQuery('.contact-form-submit').on('click', function() {
                pmw.trackCustomFacebookEvent('ContactFormClick');
            });
        });
    </script>
    <?php
});

Example: Modify Conversion Values

/wp-content/themes/child-theme/functions.php

add_action('wp_footer', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            // Subtract shipping from conversion value
            pmw.hooks.addFilter('pmw_event_data', 'exclude-shipping', function(eventData) {
                if (eventData.event_name === 'purchase' && pmwDataLayer.order) {
                    eventData.value = eventData.value - pmwDataLayer.order.shipping;
                }
                return eventData;
            });
        });
    </script>
    <?php
});

Example: Enhanced Ecommerce Tracking

/wp-content/themes/child-theme/functions.php

add_action('wp_footer', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            // Send enhanced data to Google Tag Manager
            jQuery(document).on('pmw:add-to-cart', function(event, product) {
                dataLayer.push({
                    event: 'enhanced_add_to_cart',
                    ecommerce: {
                        currencyCode: product.currency,
                        add: {
                            products: [{
                                name: product.name,
                                id: product.id,
                                price: product.price,
                                brand: product.brand || '',
                                category: product.category || '',
                                quantity: product.quantity || 1
                            }]
                        }
                    }
                });
            });
        });
    </script>
    <?php
});

Available Pixel Manager Functions

Once inside the Command Queue, you have access to all Pixel Manager API functions:

Event Tracking Functions

// Track custom Facebook events
pmw.trackCustomFacebookEvent(eventName, customData);

// Access the console logger (if enabled)
pmw.console.log(message, data);

Filter and Hook System

// Add a filter
pmw.hooks.addFilter(hookName, namespace, callback, priority);

// Add an action
pmw.hooks.addAction(hookName, namespace, callback, priority);

// Remove a filter
pmw.hooks.removeFilter(hookName, namespace);

// Remove an action
pmw.hooks.removeAction(hookName, namespace);

Data Access

// Access the data layer
console.log(pmwDataLayer);

// Access specific data
if (pmwDataLayer.shop) {
    console.log('Currency:', pmwDataLayer.shop.currency);
}

if (pmwDataLayer.order) {
    console.log('Order ID:', pmwDataLayer.order.id);
}

Event Reference

Public API Events (Recommended)

Available Since Version 1.52.0

The pmw:event:* namespace is the official public API for third-party integrations. These events provide the fully processed payload including all pixel-specific data and consent status.

Listen to these events to receive complete, processed event data:

• pmw:event:page-view - Page view with full context
• pmw:event:view-item - Product page viewed
• pmw:event:view-item-list - Product list/category viewed
• pmw:event:select-item - Product clicked/selected
• pmw:event:add-to-cart - Product added to cart
• pmw:event:remove-from-cart - Product removed from cart
• pmw:event:view-cart - Cart page viewed
• pmw:event:begin-checkout - Checkout started
• pmw:event:add-payment-info - Payment method selected
• pmw:event:add-shipping-info - Shipping method selected
• pmw:event:purchase - Order completed
• pmw:event:add-to-wishlist - Product added to wishlist
• pmw:event:search - Search performed

Example:

window._pmwq = window._pmwq || [];
window._pmwq.push(function() {
    jQuery(document).on('pmw:event:add-to-cart', function(event, payload) {
        console.log('Add to cart event:', payload);
        console.log('Event name:', payload.event);
        console.log('Product data:', payload.event_data);
        console.log('Pixel-specific data:', payload.pixels);
    });
});

Entry Point Events (Legacy, Still Supported)

These original events are still triggered and will continue to work for backwards compatibility:

• pmw:page-view - Page view
• pmw:view-item - Product page viewed
• pmw:view-category - Category page viewed
• pmw:search - Search performed
• pmw:add-to-cart - Product added to cart
• pmw:remove-from-cart - Product removed from cart
• pmw:select-item - Product clicked/selected
• pmw:add-to-wishlist - Product added to wishlist
• pmw:begin-checkout - Checkout started
• pmw:add-payment-info - Payment method selected
• pmw:place-order - Order placement initiated
• pmw:purchase - Order completed
• pmw:login - User logged in

Difference Between Event Types

• pmw:event:* events contain the fully processed payload with all pixel adaptations and firing decisions
• pmw:* events are entry point events with raw event data before processing

For most use cases, the pmw:event:* events provide more complete information.

Troubleshooting

Command Not Executing

Problem: Your command doesn't seem to run.

Solution: Enable the Console Logger to verify when Pixel Manager loads:

window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    console.log('This message confirms the command executed');
});

Function Not Found

Problem: pmw.someFunction is not a function error.

Solution: Verify you're calling functions that exist in the Pixel Manager API. Check the Event Filters documentation for available functions.

Best Practices

1. Always initialize the queue first

   window._pmwq = window._pmwq || [];

2. Keep commands focused - One command should do one thing

   // Good
   window._pmwq.push(function() {
       pmw.hooks.addFilter('pmw_event_data', 'my-filter', callback);
   });
   
   // Avoid mixing unrelated operations in one command

3. Use meaningful namespace identifiers in filters

   pmw.hooks.addFilter('pmw_event_data', 'my-shop-exclude-shipping', callback);
   // Not: pmw.hooks.addFilter('pmw_event_data', 'filter1', callback);

4. Handle errors gracefully

   window._pmwq.push(function() {
       try {
           // Your code
       } catch(e) {
           console.error('Error:', e);
       }
   });

5. Test with Console Logger enabled - Use ?pmwloggeron to verify your code runs correctly

Related Documentation

• Event Filters - Modify tracking data with filters and hooks
• Console Logger - Debug your Command Queue implementations
• Tips and Tricks - More code examples and patterns
• PHP Filters - Server-side WordPress/WooCommerce filters