FB Pixel: Custom Content Types and Automatic Configuration (segmentio#59)

* Fixes facade call and adds tests

* allow disable autoConfig

* Fixes tests

* Bumps Facebook Pixel version

* Updates HISTORY

* Updates auto configuration naming

* Replaces free form content type with a mapped setting + defaults

* Removes ununused block

Author: gpsamson

integrations/facebook-pixel/HISTORY.md

@@ -1,3 +1,10 @@
+2.5.1 / 2018-09-10
+==================
+
+  * Makes content type customizable for Product List Viewed, Product Viewed, Product Added, and
+  Order Completed events.
+  * Adds a setting to disable Automatic Configuration.
+
 2.5.0 / 2018-06-22
 ==================
 

integrations/facebook-pixel/lib/index.js

@@ -24,8 +24,10 @@ var FacebookPixel = module.exports = integration('Facebook Pixel')
   .option('valueIdentifier', 'value')
   .option('initWithExistingTraits', false)
   .option('traverse', false)
+  .option('automaticConfiguration', true)
   .mapping('standardEvents')
   .mapping('legacyEvents')
+  .mapping('contentTypes')
   .tag('<script src="//connect.facebook.net/en_US/fbevents.js">');
 
 /**
@@ -52,6 +54,9 @@ FacebookPixel.prototype.initialize = function() {
   window.fbq.version = '2.0';
   window.fbq.queue = [];
   this.load(this.ready);
+  if (!this.options.automaticConfiguration) {
+    window.fbq('set', 'autoConfig', false, this.options.pixelId);
+  }
   if (this.options.initWithExistingTraits) {
     var traits = formatTraits(this.analytics);
     window.fbq('init', this.options.pixelId, traits);
@@ -183,15 +188,15 @@ FacebookPixel.prototype.productListViewed = function(track) {
   // If no products have been defined, fallback on legacy behavior.
   // Facebook documents the content_type parameter decision here: https://developers.facebook.com/docs/facebook-pixel/api-reference
   if (contentIds.length) {
-    contentType = 'product';
+    contentType = ['product'];
   } else {
     contentIds.push(track.category() || '');
-    contentType = 'product_group';
+    contentType = ['product_group'];
   }
 
   window.fbq('track', 'ViewContent', {
     content_ids: contentIds,
-    content_type: contentType
+    content_type: this.mappedContentTypesOrDefault(track.category(), contentType), 
   });
 
   // fall through for mapped legacy conversions
@@ -213,7 +218,7 @@ FacebookPixel.prototype.productListViewed = function(track) {
 FacebookPixel.prototype.productViewed = function(track) {
   window.fbq('track', 'ViewContent', {
     content_ids: [track.productId() || track.id() || track.sku() || ''],
-    content_type: 'product',
+    content_type: this.mappedContentTypesOrDefault(track.category(), ['product']),
     content_name: track.name() || '',
     content_category: track.category() || '',
     currency: track.currency(),
@@ -239,7 +244,7 @@ FacebookPixel.prototype.productViewed = function(track) {
 FacebookPixel.prototype.productAdded = function(track) {
   window.fbq('track', 'AddToCart', {
     content_ids: [track.productId() || track.id() || track.sku() || ''],
-    content_type: 'product',
+    content_type: this.mappedContentTypesOrDefault(track.category(), ['product']),
     content_name: track.name() || '',
     content_category: track.category() || '',
     currency: track.currency(),
@@ -263,18 +268,27 @@ FacebookPixel.prototype.productAdded = function(track) {
  */
 
 FacebookPixel.prototype.orderCompleted = function(track) {
+  var products = track.products() || [];
+
   var content_ids = foldl(function(acc, product) {
     var item = new Track({ properties: product });
     var key = item.productId() || item.id() || item.sku();
     if (key) acc.push(key);
     return acc;
-  }, [], track.products() || []);
+  }, [], products);
 
   var revenue = formatRevenue(track.revenue());
 
+  // Order completed doesn't have a top-level category spec'd.
+  // Let's default to the category of the first product. - @gabriel
+  var contentType = ['product_group'];
+  if (products.length) {
+    contentType = this.mappedContentTypesOrDefault(products[0].category, contentType);
+  }
+
   window.fbq('track', 'Purchase', {
     content_ids: content_ids,
-    content_type: 'product',
+    content_type: contentType,
     currency: track.currency(),
     value: revenue
   });
@@ -288,6 +302,22 @@ FacebookPixel.prototype.orderCompleted = function(track) {
   }, this.legacyEvents(track.event()));
 };
 
+/**
+ * mappedContentTypesOrDefault returns an array of mapped content types for
+ * the category - or returns the defaul value.
+ * @param {Facade.Track} track 
+ * @param {Array} def 
+ */
+FacebookPixel.prototype.mappedContentTypesOrDefault = function(category, def) {
+  if (!category) return def
+
+  var mapped = this.contentTypes(category);
+  if (mapped.length) {
+    return mapped
+  } 
+  
+  return def
+}
 
 /**
  * Get Revenue Formatted Correctly for FB.

integrations/facebook-pixel/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@segment/analytics.js-integration-facebook-pixel",
   "description": "The Facebook Pixel analytics.js integration.",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "keywords": [
     "analytics.js",
     "analytics.js-integration",

integrations/facebook-pixel/test/index.test.js

@@ -9,6 +9,7 @@ describe('Facebook Pixel', function() {
   var analytics;
   var facebookPixel;
   var options = {
+    automaticConfiguration: true,
     legacyEvents: {
       legacyEvent: 'asdFrkj'
     },
@@ -17,6 +18,9 @@ describe('Facebook Pixel', function() {
       'booking completed': 'Purchase',
       search: 'Search'
     },
+    contentTypes: {
+      Cars: "vehicle"
+    },
     pixelId: '123123123',
     agent: 'test',
     initWithExistingTraits: false
@@ -86,6 +90,20 @@ describe('Facebook Pixel', function() {
         analytics.assert(window.fbq instanceof Function);
       });
 
+      before(function() {
+        options.automaticConfiguration = false;
+      });
+
+      after(function() {
+        options.automaticConfiguration = true;
+      });
+
+      it('should call set autoConfig if option disableAutoConfig is enabled', function () {
+        analytics.stub(window, 'fbq');
+        analytics.initialize();
+        analytics.called(window.fbq, 'set', 'autoConfig', false, options.pixelId);
+      });
+
       before(function() {
         options.initWithExistingTraits = true;
       });
@@ -225,7 +243,6 @@ describe('Facebook Pixel', function() {
             property: true
           });
         });
-
         describe('Dyanmic Ads for Travel date parsing', function() {
           it('should correctly pass in iso8601 formatted date objects', function() {
             analytics.track('search', {
@@ -260,7 +277,7 @@ describe('Facebook Pixel', function() {
                   name: 'Monopoly: 3rd Edition',
                   price: 19,
                   position: 1,
-                  category: 'Games',
+                  category: 'Cars',
                   url: 'https://www.example.com/product/path',
                   image_url: 'https://www.example.com/product/path.jpg'
                 },
@@ -270,23 +287,52 @@ describe('Facebook Pixel', function() {
                   name: 'Uno Card Game',
                   price: 3,
                   position: 2,
-                  category: 'Games'
+                  category: 'Cars'
                 }
               ]
             });
             analytics.called(window.fbq, 'track', 'ViewContent', {
               content_ids: ['507f1f77bcf86cd799439011', '505bd76785ebb509fc183733'],
-              content_type: 'product'
+              content_type: ['product']
             });
           });
 
           it('Should fallback on mapping content_ids to the product category and content_type to "product_group"', function() {
             analytics.track('Product List Viewed', { category: 'Games' });
             analytics.called(window.fbq, 'track', 'ViewContent', {
               content_ids: ['Games'],
-              content_type: 'product_group'
+              content_type: ['product_group']
             });
           });
+
+          it('should send the custom content type if mapped', function() {
+            analytics.track('Product List Viewed', {
+              category: 'Cars', products: [
+                {
+                  product_id: '507f1f77bcf86cd799439011',
+                  sku: '45790-32',
+                  name: 'Monopoly: 3rd Edition',
+                  price: 19,
+                  position: 1,
+                  category: 'Games',
+                  url: 'https://www.example.com/product/path',
+                  image_url: 'https://www.example.com/product/path.jpg'
+                },
+                {
+                  product_id: '505bd76785ebb509fc183733',
+                  sku: '46493-32',
+                  name: 'Uno Card Game',
+                  price: 3,
+                  position: 2,
+                  category: 'Games'
+                }
+              ]
+            });
+            analytics.called(window.fbq, 'track', 'ViewContent', {
+              content_ids: ['507f1f77bcf86cd799439011', '505bd76785ebb509fc183733'],
+              content_type: ['vehicle']
+            });
+          })
         });
 
         it('Product Viewed', function() {
@@ -302,7 +348,7 @@ describe('Facebook Pixel', function() {
           });
           analytics.called(window.fbq, 'track', 'ViewContent', {
             content_ids: ['507f1f77bcf86cd799439011'],
-            content_type: 'product',
+            content_type: ['product'],
             content_name: 'my product',
             content_category: 'cat 1',
             currency: 'USD',
@@ -324,14 +370,35 @@ describe('Facebook Pixel', function() {
           });
           analytics.called(window.fbq, 'track', 'ViewContent', {
             content_ids: ['507f1f77bcf86cd799439011'],
-            content_type: 'product',
+            content_type: ['product'],
             content_name: 'my product',
             content_category: 'cat 1',
             currency: 'USD',
             value: '44.33'
           });
         });
 
+        it('should send the custom content type if mapped', function() {
+          analytics.track('Product Viewed', {
+            product_id: '507f1f77bcf86cd799439011',
+            currency: 'USD',
+            quantity: 1,
+            price: 44.33,
+            name: 'my product',
+            category: 'Cars',
+            sku: 'p-298',
+            value: 24.75,
+          });
+          analytics.called(window.fbq, 'track', 'ViewContent', {
+            content_ids: ['507f1f77bcf86cd799439011'],
+            content_type: ['vehicle'],
+            content_name: 'my product',
+            content_category: 'Cars',
+            currency: 'USD',
+            value: '24.75'
+          });
+        })
+
         it('Adding to Cart', function() {
           analytics.track('Product Added', {
             product_id: '507f1f77bcf86cd799439011',
@@ -345,7 +412,7 @@ describe('Facebook Pixel', function() {
           });
           analytics.called(window.fbq, 'track', 'AddToCart', {
             content_ids: ['507f1f77bcf86cd799439011'],
-            content_type: 'product',
+            content_type: ['product'],
             content_name: 'my product',
             content_category: 'cat 1',
             currency: 'USD',
@@ -367,14 +434,36 @@ describe('Facebook Pixel', function() {
           });
           analytics.called(window.fbq, 'track', 'AddToCart', {
             content_ids: ['507f1f77bcf86cd799439011'],
-            content_type: 'product',
+            content_type: ['product'],
             content_name: 'my product',
             content_category: 'cat 1',
             currency: 'USD',
             value: '44.33'
           });
         });
 
+        it('should send the custom content type if mapped', function() {
+          analytics.track('Product Added', {
+            product_id: '507f1f77bcf86cd799439011',
+            currency: 'USD',
+            quantity: 1,
+            price: 44.33,
+            name: 'my product',
+            category: 'Cars',
+            sku: 'p-298',
+            value: 24.75,
+            content_type: "stuff"
+          });
+          analytics.called(window.fbq, 'track', 'AddToCart', {
+            content_ids: ['507f1f77bcf86cd799439011'],
+            content_type: ['vehicle'],
+            content_name: 'my product',
+            content_category: 'Cars',
+            currency: 'USD',
+            value: '24.75'
+          });
+        })
+
         it('Completing an Order', function() {
           analytics.track('Order Completed', {
             products: [
@@ -386,7 +475,7 @@ describe('Facebook Pixel', function() {
           });
           analytics.called(window.fbq, 'track', 'Purchase', {
             content_ids: ['507f1f77bcf86cd799439011', '505bd76785ebb509fc183733'],
-            content_type: 'product',
+            content_type: ['product_group'],
             currency: 'USD',
             value: '0.50'
           });
@@ -404,7 +493,7 @@ describe('Facebook Pixel', function() {
           });
           analytics.called(window.fbq, 'track', 'Purchase', {
             content_ids: ['507f1f77bcf86cd799439011', '505bd76785ebb509fc183733'],
-            content_type: 'product',
+            content_type: ['product_group'],
             currency: 'USD',
             value: '0.50'
           });
@@ -413,6 +502,23 @@ describe('Facebook Pixel', function() {
             value: '0.50'
           });
         });
+
+        it('should send the custom content type if mapped', function() {
+          analytics.track('Order Completed', {
+            products: [
+              { product_id: '507f1f77bcf86cd799439011', category: 'Cars' },
+              { product_id: '505bd76785ebb509fc183733', category: 'Cars' }
+            ],
+            currency: 'USD',
+            total: 0.50,
+          });
+          analytics.called(window.fbq, 'track', 'Purchase', {
+            content_ids: ['507f1f77bcf86cd799439011', '505bd76785ebb509fc183733'],
+            content_type: ['vehicle'],
+            currency: 'USD',
+            value: '0.50'
+          });
+        })
       });
     });
   });