feat: SDKE-482 support custom product attributes (#49)

Author: jaissica12

src/FacebookEventForwarder.js

@@ -60,11 +60,14 @@
         constructor = function () {
             var self = this,
                 isInitialized = false,
-                reportingService = null;
+                reportingService = null,
+                settings,
+                productAttributeMapping;
 
             self.name = name;
 
-            function initForwarder(settings, service, testMode, trackerId, userAttributes, userIdentities) {
+            function initForwarder(forwarderSettings, service, testMode, trackerId, userAttributes, userIdentities) {
+                settings = forwarderSettings;
                 reportingService = service;
 
                 SupportedCommerceTypes = [
@@ -107,6 +110,8 @@
                         fbq.disablePushState = true;
                     }
                     fbq('init', settings.pixelId, visitorData);
+                    
+                    loadMappings();
 
                     isInitialized = true;
 
@@ -118,6 +123,12 @@
                 }
             }
 
+            function loadMappings() {
+                productAttributeMapping = settings.productAttributeMapping
+                ? JSON.parse(settings.productAttributeMapping.replace(/"/g, '"'))
+                : [];
+            }
+
             function processEvent(event) {
                 var reportEvent = false;
 
@@ -212,7 +223,7 @@
 
                     }
                     else if (event.ProductAction.ProductActionType == mParticle.ProductActionType.Checkout ||
-                             event.ProductAction.ProductActionType == mParticle.ProductActionType.Purchase) {
+                            event.ProductAction.ProductActionType == mParticle.ProductActionType.Purchase) {
 
                         eventName = event.ProductAction.ProductActionType == mParticle.ProductActionType.Checkout ? CHECKOUT_EVENT_NAME : PURCHASE_EVENT_NAME;
 
@@ -227,6 +238,18 @@
                             return sum;
                         }, 0);
                         params['num_items'] = num_items;
+                        
+                        if (event.ProductAction.TransactionId) {
+                            params['order_id'] = event.ProductAction.TransactionId;
+                        }
+
+                        // Build contents array for Purchase events
+                        if (event.ProductAction.ProductActionType == mParticle.ProductActionType.Purchase) {
+                            var contents = buildProductContents(event.ProductAction.ProductList);
+                            if (contents && contents.length > 0) {
+                                params['contents'] = contents;
+                            }
+                        }
                     }
                     else if (event.ProductAction.ProductActionType == mParticle.ProductActionType.RemoveFromCart) {
                         eventName = REMOVE_FROM_CART_EVENT_NAME;
@@ -323,6 +346,60 @@
                 return null;
             }
 
+            /**
+             * Builds contents array for Facebook Pixel commerce events.
+             * Creates a nested array of content items with product details.
+             * 
+             * @param {Array} productList - Array of products from event.ProductAction.ProductList
+             * @returns {Array} Array of content objects for Facebook Pixel
+             */
+            function buildProductContents(productList) {
+                if (!productList || productList.length === 0) {
+                    return [];
+                }
+            
+                return productList
+                    .filter(function(product) {
+                        return product && product.Sku;
+                    })
+                    .map(function(product) {
+                        var contentItem = {
+                            id: product.Sku,
+                            quantity: isNumeric(product.Quantity) ? product.Quantity : 1,
+                            name: product.Name,
+                            brand: product.Brand,
+                            category: product.Category,
+                            variant: product.Variant,
+                            item_price: isNumeric(product.Price) ? product.Price : null
+                        };
+            
+                        // Apply configured mappings to custom attributes
+                        productAttributeMapping.forEach(function(productMapping) {
+                            if (!isobject(productMapping) || !productMapping.map || !productMapping.value) {
+                                return;
+                            }
+                            
+                            var sourceField = productMapping.map;
+                            var facebookFieldName = productMapping.value;
+                            var value = null;
+                            
+                            // Check for Product level field first
+                            if (product.hasOwnProperty(sourceField)) {
+                                value = product[sourceField];
+                            }
+                            // then check for Product.Attributes level field
+                            else if (product.Attributes && product.Attributes[sourceField]) {
+                                value = product.Attributes[sourceField];
+                            }
+                            
+                            if (value !== null && value !== undefined) {
+                                contentItem[facebookFieldName] = value;
+                            }
+                        });
+                        return contentItem;
+                    });
+            }
+
             // https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events#event-deduplication-options
             function createEventId(event) {
                 return {

test/tests.js

@@ -481,6 +481,7 @@ describe('Facebook Forwarder', function () {
             window.fbqObj.params.should.have.property('content_name', 'eCommerce - AddToCart');
             window.fbqObj.params.should.have.property('content_ids', ['12345']);
             window.fbqObj.eventData.should.have.property('eventID', SOURCE_MESSAGE_ID);
+            window.fbqObj.params.should.not.have.property('contents');
 
             done();
         });
@@ -857,5 +858,71 @@ describe('Facebook Forwarder', function () {
             window.fbqObj.should.have.property('trackCalled', false);
             done();
         });
+
+        it('should build contents array with mapped attributes for Purchase events', function (done) {
+            // Initialize with product attribute mapping
+            mParticle.forwarder.init({
+                pixelCode: 'test-pixel-code',
+                "productAttributeMapping":"[{"jsmap":"3373707","map":"Name","maptype":"ProductAttributeSelector.Name","value":"custom_name"},{"jsmap":"93997959","map":"Brand","maptype":"ProductAttributeSelector.Name","value":"custom_brand"},{"jsmap":"106934601","map":"Price","maptype":"ProductAttributeSelector.Name","value":"custom_price"},{"jsmap":"50511102","map":"Category","maptype":"ProductAttributeSelector.Name","value":"custom_category"},{"jsmap":"94842723","map":"category","maptype":"ProductAttributeSelector.Name","value":"custom_attribute_category"}]"
+            }, reportService.cb, true);
+
+            mParticle.forwarder.process({
+                EventName: 'eCommerce - Purchase',
+                EventDataType: MessageType.Commerce,
+                ProductAction: {
+                    ProductActionType: ProductActionType.Purchase,
+                    ProductList: [
+                        {
+                            Sku: 'sku-12',
+                            Name: 'iPhone',
+                            Brand: 'Apple',
+                            Category: 'electronics',
+                            Variant: 'blue',
+                            Price: 1000.99,
+                            Quantity: 1,
+                            Attributes: {
+                                category: 'phones'
+                            }
+                        },
+                        {
+                            Sku: 'sku-34',
+                            Name: 'Watch',
+                            Brand: 'Samsung',
+                            Price: 450.99,
+                            Quantity: 2
+                        }
+                    ],
+                    TransactionId: 'txn-1234',
+                    TotalAmount: 1451.98
+                },
+                CurrencyCode: 'USD',
+                SourceMessageId: SOURCE_MESSAGE_ID,
+            });
+
+            checkBasicProperties('track');
+            window.fbqObj.should.have.property('eventName', 'Purchase');
+            window.fbqObj.params.should.have.property('order_id', 'txn-1234');
+            window.fbqObj.params.should.have.property('contents');
+            window.fbqObj.params.contents.length.should.equal(2);
+            
+            var firstProduct = window.fbqObj.params.contents[0];
+            // Standard Facebook fields
+            firstProduct.should.have.property('id', 'sku-12');
+            firstProduct.should.have.property('name', 'iPhone');
+            firstProduct.should.have.property('brand', 'Apple');
+            firstProduct.should.have.property('item_price', 1000.99);
+            firstProduct.should.have.property('quantity', 1);
+            
+            // Mapped standard fields
+            firstProduct.should.have.property('custom_name', 'iPhone');
+            firstProduct.should.have.property('custom_brand', 'Apple');
+            firstProduct.should.have.property('custom_price', 1000.99);
+            firstProduct.should.have.property('custom_category', 'electronics');
+            
+            // Mapped custom attribute
+            firstProduct.should.have.property('custom_attribute_category', 'phones');
+
+            done();
+        });
     });
 });