@mparticle/web-amplitude-kit 2.2.0 → 2.3.0

package/dist/Amplitude.common.js

@@ -1,16 +1,5 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
-/*!
- * isobject <https://github.com/jonschlinkert/isobject>
- *
- * Copyright (c) 2014-2017, Jon Schlinkert.
- * Released under the MIT License.
- */
-
-function isObject(val) {
-  return val != null && typeof val === 'object' && Array.isArray(val) === false;
-}
-
 /* eslint-disable no-undef*/
 //
 //  Copyright 2015 mParticle, Inc.
@@ -27,8 +16,6 @@ function isObject(val) {
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-
-
 var name = 'Amplitude',
     moduleId = 53,
     MessageType = {
@@ -57,32 +44,48 @@ var constants = {
     other10: 'other10',
 };
 
+var MP_AMP_SPLIT = 'mparticle_amplitude_should_split',
+    TOTAL_AMOUNT = 'Total Amount',
+    TOTAL = 'Total',
+    PRODUCTS = 'products',
+    REFUND = 'Refund',
+    PURCHASE = 'Purchase',
+    TOTAL_PRODUCT_AMOUNT = 'Total Product Amount';
+
+var includeIndividualProductEvents,
+    shouldSendSeparateAmplitudeRevenueEvent,
+    enableTempAmplitudeEcommerce;
+
 /* eslint-disable */
 // prettier-ignore
 var renderSnippet = function() {
-        (function(e,t){var n=e.amplitude||{_q:[],_iq:{}};var r=t.createElement("script")
-        ;r.type="text/javascript"
-        ;r.integrity="sha384-girahbTbYZ9tT03PWWj0mEVgyxtZoyDF9KVZdL+R53PP5wCY0PiVUKq0jeRlMx9M"
-        ;r.crossOrigin="anonymous";r.async=true
-        ;r.src="https://cdn.amplitude.com/libs/amplitude-7.2.1-min.gz.js"
-        ;r.onload=function(){if(!e.amplitude.runQueuedFunctions){
-        console.log("[Amplitude] Error: could not load SDK");}}
-        ;var i=t.getElementsByTagName("script")[0];i.parentNode.insertBefore(r,i)
-        ;function s(e,t){e.prototype[t]=function(){
+        (function(e,t){var n=e.amplitude||{_q:[],_iq:{}};var r=t.createElement("script");
+        r.type="text/javascript";
+        r.integrity="sha384-QahB0HKETlcqjneomU3Ohs+UgJTinhUNFIKJitEl2Vo7DjvphO2jei64ZP5J2GA5";
+        r.crossOrigin="anonymous";r.async=true;
+        r.src="https://cdn.amplitude.com/libs/amplitude-8.21.8-min.gz.js";
+        r.onload=function(){if(!e.amplitude.runQueuedFunctions){console.log(
+        "[Amplitude] Error: could not load SDK");}};var s=t.getElementsByTagName("script"
+        )[0];s.parentNode.insertBefore(r,s);function i(e,t){e.prototype[t]=function(){
         this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));return this};}
-        var o=function(){this._q=[];return this}
-        ;var a=["add","append","clearAll","prepend","set","setOnce","unset"]
-        ;for(var c=0;c<a.length;c++){s(o,a[c]);}n.Identify=o;var u=function(){this._q=[]
-        ;return this}
-        ;var l=["setProductId","setQuantity","setPrice","setRevenueType","setEventProperties"]
-        ;for(var p=0;p<l.length;p++){s(u,l[p]);}n.Revenue=u
-        ;var d=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","enableTracking","setGlobalUserProperties","identify","clearUserProperties","setGroup","logRevenueV2","regenerateDeviceId","groupIdentify","onInit","logEventWithTimestamp","logEventWithGroups","setSessionId","resetSessionId"]
-        ;function v(e){function t(t){e[t]=function(){
-        e._q.push([t].concat(Array.prototype.slice.call(arguments,0)));};}
-        for(var n=0;n<d.length;n++){t(d[n]);}}v(n);n.getInstance=function(e){
-        e=(!e||e.length===0?"$default_instance":e).toLowerCase()
-        ;if(!n._iq.hasOwnProperty(e)){n._iq[e]={_q:[]};v(n._iq[e]);}return n._iq[e]}
-        ;e.amplitude=n;})(window,document);
+        var o=function(){this._q=[];return this};var a=["add","append","clearAll",
+        "prepend","set","setOnce","unset","preInsert","postInsert","remove"];for(
+        var c=0;c<a.length;c++){i(o,a[c]);}n.Identify=o;var l=function(){this._q=[];
+        return this};var p=["setProductId","setQuantity","setPrice","setRevenueType",
+        "setEventProperties"];for(var u=0;u<p.length;u++){i(l,p[u]);}n.Revenue=l;var d=[
+        "init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut",
+        "setVersionName","setDomain","setDeviceId","enableTracking",
+        "setGlobalUserProperties","identify","clearUserProperties","setGroup",
+        "logRevenueV2","regenerateDeviceId","groupIdentify","onInit","onNewSessionStart"
+        ,"logEventWithTimestamp","logEventWithGroups","setSessionId","resetSessionId",
+        "getDeviceId","getUserId","setMinTimeBetweenSessionsMillis",
+        "setEventUploadThreshold","setUseDynamicConfig","setServerZone","setServerUrl",
+        "sendEvents","setLibrary","setTransport"];function v(t){function e(e){t[e
+        ]=function(){t._q.push([e].concat(Array.prototype.slice.call(arguments,0)));};}
+        for(var n=0;n<d.length;n++){e(d[n]);}}v(n);n.getInstance=function(e){e=(
+        !e||e.length===0?"$default_instance":e).toLowerCase();if(
+        !Object.prototype.hasOwnProperty.call(n._iq,e)){n._iq[e]={_q:[]};v(n._iq[e]);}
+        return n._iq[e]};e.amplitude=n;})(window,document);
         /* eslint-enable */
 };
 
@@ -341,7 +344,7 @@ var constructor = function () {
     function createEcommerceAttributes(attributes) {
         var updatedAttributes = {};
         for (var key in attributes) {
-            if (key !== 'Total Amount' && key !== 'Total Product Amount') {
+            if (key !== TOTAL_AMOUNT && key !== TOTAL_PRODUCT_AMOUNT) {
                 updatedAttributes[key] = attributes[key];
             }
         }
@@ -351,62 +354,263 @@ var constructor = function () {
 
     function logCommerce(event) {
         var expandedEvents = mParticle.eCommerce.expandCommerceEvent(event);
+        // if Product Action exists, it's a regular product action commerce event
         if (event.ProductAction) {
-            var isRefund, isPurchase, logRevenue;
-            isRefund =
-                event.ProductAction.ProductActionType ===
-                mParticle.ProductActionType.Refund;
-            isPurchase =
-                event.ProductAction.ProductActionType ===
-                mParticle.ProductActionType.Purchase;
-            logRevenue = isRefund || isPurchase;
+            if (enableTempAmplitudeEcommerce) {
+                return processTemporaryProductAction(event, expandedEvents);
+            } else {
+                // TODO: Remove this old code path when Amplitude is ready
+                var isRefund, isPurchase, logRevenue;
+                isRefund =
+                    event.ProductAction.ProductActionType ===
+                    mParticle.ProductActionType.Refund;
+                isPurchase =
+                    event.ProductAction.ProductActionType ===
+                    mParticle.ProductActionType.Purchase;
+                logRevenue = isRefund || isPurchase;
+                expandedEvents.forEach(function (expandedEvt) {
+                    // Exclude Totals from the attributes as we log it in the revenue call
+                    var updatedAttributes = createEcommerceAttributes(
+                        expandedEvt.EventAttributes
+                    );
+
+                    // Purchase and Refund events generate an additional 'Total' event
+                    if (
+                        logRevenue &&
+                        expandedEvt.EventName.indexOf('Total') > -1
+                    ) {
+                        var revenueAmount =
+                            (expandedEvt.EventAttributes['Total Amount'] || 0) *
+                            (isRefund ? -1 : 1);
+                        var revenue = new window.amplitude.Revenue()
+                            .setPrice(revenueAmount)
+                            .setEventProperties(updatedAttributes);
+                        getInstance().logRevenueV2(revenue);
+                    } else {
+                        getInstance().logEvent(
+                            expandedEvt.EventName,
+                            updatedAttributes
+                        );
+                    }
+                });
+
+                return true;
+            }
+        }
+
+        // if it is not a product action, it is an impression or promotion commerce event
+        if (isNotProductAction(event)) {
             expandedEvents.forEach(function (expandedEvt) {
                 // Exclude Totals from the attributes as we log it in the revenue call
                 var updatedAttributes = createEcommerceAttributes(
                     expandedEvt.EventAttributes
                 );
 
-                // Purchase and Refund events generate an additional 'Total' event
-                if (logRevenue && expandedEvt.EventName.indexOf('Total') > -1) {
-                    var revenueAmount =
-                        (expandedEvt.EventAttributes['Total Amount'] || 0) *
-                        (isRefund ? -1 : 1);
-                    var revenue = new window.amplitude.Revenue()
-                        .setPrice(revenueAmount)
-                        .setEventProperties(updatedAttributes);
-                    getInstance().logRevenueV2(revenue);
-                } else {
-                    getInstance().logEvent(
-                        expandedEvt.EventName,
-                        updatedAttributes
-                    );
-                }
+                getInstance().logEvent(
+                    expandedEvt.EventName,
+                    updatedAttributes
+                );
             });
 
             return true;
         }
 
+        console.warn(
+            'Commerce event does not conform to our expectations and was not forwarded to Amplitude. Please double-check your code.'
+        );
+
+        return false;
+    }
+
+    /*
+    When we process a product action event, Amplitude has a very specific way of
+    sending events to them:
+
+    1.  Send a summary event with event attributes from the MP event.
+        a.  Add a key of `products` with a value of JSON.stringify(productArray).
+        b.  Add a key of mparticle_amplitude_should_split with a value of `false`.
+
+    2.  Determine if we send product level events or not.
+        a.  If includeIndividualProductEvents === true, send product level events
+        b.  If includeIndividualProductEvents === false, do not send product level events
+
+    3.  Determine if we send an Amplitude revenue event or not.
+        a.  If shouldSendSeparateAmplitudeRevenueEvent === true, send an Amplitude revenue event.
+        b.  If shouldSendSeparateAmplitudeRevenueEvent === true, the summary event attribute should be `revenue`.
+        c.  If shouldSendSeparateAmplitudeRevenueEvent === false, the summary event attribute should be `$revenue`
+
+    See test/AmplitudeCommerceEvent.MD for examples of what the expectations of the payload are.
+
+     */
+    function processTemporaryProductAction(
+        unexpandedCommerceEvent,
+        expandedEvents
+    ) {
+        var summaryEvent, isRefund, isPurchase, isMPRevenueEvent;
+
+        isRefund =
+            unexpandedCommerceEvent.ProductAction.ProductActionType ===
+            mParticle.ProductActionType.Refund;
+        isPurchase =
+            unexpandedCommerceEvent.ProductAction.ProductActionType ===
+            mParticle.ProductActionType.Purchase;
+        isMPRevenueEvent = isRefund || isPurchase;
+
+        // if the event is a revenue event, then we set it to the expanded `Total` event for backwards compatibility
         if (
+            isMPRevenueEvent &&
+            expandedEvents[0].EventName.indexOf(TOTAL) > -1
+        ) {
+            summaryEvent = expandedEvents[0];
+            sendMPRevenueSummaryEvent(
+                summaryEvent,
+                unexpandedCommerceEvent.ProductAction.ProductList,
+                isRefund,
+                shouldSendSeparateAmplitudeRevenueEvent
+            );
+        }
+
+        if (!isMPRevenueEvent) {
+            sendSummaryEvent(unexpandedCommerceEvent);
+        }
+
+        if (includeIndividualProductEvents) {
+            sendIndividualProductEvents(
+                expandedEvents,
+                isMPRevenueEvent,
+                shouldSendSeparateAmplitudeRevenueEvent,
+                isRefund
+            );
+        }
+
+        return true;
+    }
+
+    // If event.ProductAction does not exist, the commerce event is a promotion or impression event
+    function isNotProductAction(event) {
+        return (
             event.EventCategory ===
                 mParticle.CommerceEventType.ProductImpression ||
             event.EventCategory === mParticle.CommerceEventType.PromotionView ||
             event.EventCategory === mParticle.CommerceEventType.PromotionClick
-        ) {
-            expandedEvents.forEach(function (expandedEvt) {
-                // Exclude Totals from the attributes as we log it in the revenue call
-                var updatedAttributes = createEcommerceAttributes(
+        );
+    }
+
+    // this function does not use Amplitude's logRevenueV2, but rather sends custom event names
+    function sendMPRevenueSummaryEvent(
+        summaryEvent,
+        products,
+        isRefund,
+        shouldSendSeparateAmplitudeRevenueEvent
+    ) {
+        // send the ecommerce - purchase event
+        var updatedAttributes = createMPRevenueEcommerceAttributes(
+            summaryEvent.EventAttributes,
+            shouldSendSeparateAmplitudeRevenueEvent,
+            isRefund
+        );
+        updatedAttributes[MP_AMP_SPLIT] = false;
+
+        updatedAttributes[PRODUCTS] = products;
+        var revenueEventLabel = isRefund ? REFUND : PURCHASE;
+        getInstance().logEvent(
+            'eCommerce - ' + revenueEventLabel,
+            updatedAttributes
+        );
+    }
+
+    // revenue summary event will either have $price/price or $revenue/revenue depending on if
+    function createMPRevenueEcommerceAttributes(
+        attributes,
+        shouldSendSeparateAmplitudeRevenueEvent,
+        isRefund
+    ) {
+        var updatedAttributes = {};
+        for (var key in attributes) {
+            if (key === TOTAL_AMOUNT) {
+                // A purchase is a positive amount and a refund is negative
+                var revenueAmount = attributes[key] * (isRefund ? -1 : 1);
+                // If we send a separate Amplitude Revenue Event, Amplitude's
+                // SDK prefixes price/revenue with a $ for calculating things
+                // like LTV, so we do not want to prepend it as part of the
+                // summary event to avoid double counting
+                var revenueKey = shouldSendSeparateAmplitudeRevenueEvent
+                    ? 'revenue'
+                    : '$revenue';
+
+                updatedAttributes[revenueKey] = revenueAmount;
+            } else if (key !== TOTAL_AMOUNT) {
+                updatedAttributes[key] = attributes[key];
+            }
+        }
+
+        return convertJsonAttrs(updatedAttributes);
+    }
+
+    function createAttrsForAmplitudeRevenueEvent(attributes) {
+        var updatedAttributes = {};
+        for (var key in attributes) {
+            if (key !== TOTAL_AMOUNT) {
+                updatedAttributes[key] = attributes[key];
+            }
+        }
+
+        return convertJsonAttrs(updatedAttributes);
+    }
+
+    function sendSummaryEvent(summaryEvent) {
+        var updatedAttributes = createEcommerceAttributes(
+            summaryEvent.EventAttributes
+        );
+        updatedAttributes[MP_AMP_SPLIT] = false;
+        try {
+            updatedAttributes[PRODUCTS] =
+                summaryEvent.ProductAction.ProductList;
+        } catch (e) {
+            console.error('error adding Product List to summary event');
+        }
+
+        getInstance().logEvent(summaryEvent.EventName, updatedAttributes);
+    }
+
+    function sendIndividualProductEvents(
+        expandedEvents,
+        isMPRevenueEvent,
+        shouldSendSeparateAmplitudeRevenueEvent,
+        isRefund
+    ) {
+        expandedEvents.forEach(function (expandedEvt) {
+            var updatedAttributes;
+            // `Total` exists on an expanded event if it is part of a revenue/purchase event
+            // but not on other commerce events. This only needs to be fired if shouldSendSeparateAmplitudeRevenueEvent === True
+            if (
+                isMPRevenueEvent &&
+                // A purchase is a positive amount and a refund is negative
+                (expandedEvt.EventName.indexOf(TOTAL) > -1) &
+                    shouldSendSeparateAmplitudeRevenueEvent
+            ) {
+                var revenueAmount =
+                    // A purchase is a positive amount and a refund is negative
+                    (expandedEvt.EventAttributes[TOTAL_AMOUNT] || 0) *
+                    (isRefund ? -1 : 1);
+                updatedAttributes = createAttrsForAmplitudeRevenueEvent(
                     expandedEvt.EventAttributes
                 );
 
+                var revenue = new window.amplitude.Revenue()
+                    .setPrice(revenueAmount)
+                    .setEventProperties(updatedAttributes);
+                getInstance().logRevenueV2(revenue);
+            } else if (expandedEvt.EventName.indexOf(TOTAL) === -1) {
+                updatedAttributes = createEcommerceAttributes(
+                    expandedEvt.EventAttributes
+                );
                 getInstance().logEvent(
                     expandedEvt.EventName,
                     updatedAttributes
                 );
-            });
-            return true;
-        }
-
-        return false;
+            }
+        });
     }
 
     function convertJsonAttrs(customAttributes) {
@@ -434,6 +638,15 @@ var constructor = function () {
         forwarderSettings = settings;
         reportingService = service;
 
+        // Changing this setting from a negative action to a positive action for readability
+        includeIndividualProductEvents =
+            forwarderSettings.excludeIndividualProductEvents === 'False';
+        // Only send separate amplitude revenue events when we includeIndividualProductEvents,
+        // so create this variable for clarity
+        shouldSendSeparateAmplitudeRevenueEvent = includeIndividualProductEvents;
+
+        enableTempAmplitudeEcommerce =
+            forwarderSettings.enableTempAmplitudeEcommerce === 'True';
         try {
             if (!window.amplitude) {
                 if (testMode !== true) {
@@ -525,6 +738,14 @@ function getId() {
     return moduleId;
 }
 
+function isObject(val) {
+    return (
+        val != null &&
+        typeof val === 'object' &&
+        Array.isArray(val) === false
+    );
+}
+
 function register(config) {
     if (!config) {
         console.log(

package/package.json

@@ -1,44 +1,45 @@
 {
-  "name": "@mparticle/web-amplitude-kit",
-  "version": "2.2.0",
-  "author": "mParticle Developers <developers@mparticle.com> (https://www.mparticle.com)",
-  "description": "mParticle integration sdk for Amplitude",
-  "main": "dist/Amplitude.common.js",
-  "files": [
-    "dist/Amplitude.common.js"
-  ],
-  "repository": "https://github.com/mparticle-integrations/mparticle-javascript-integration-amplitude",
-  "scripts": {
-    "build": "rollup --config rollup.config.js",
-    "dev": "npm run build && npm run test",
-    "test": "node test/boilerplate/test-karma.js",
-    "watch": "rollup --config rollup.config.js -w"
-  },
-  "devDependencies": {
-    "chai": "^4.2.0",
-    "eslint-config-prettier": "6.3.0",
-    "eslint-plugin-prettier": "3.1.1",
-    "karma": "^5.0.9",
-    "karma-chai": "^0.1.0",
-    "karma-chrome-launcher": "^2.2.0",
-    "karma-edge-launcher": "^0.4.2",
-    "karma-firefox-launcher": "^1.1.0",
-    "karma-ie-launcher": "^1.0.0",
-    "karma-junit-reporter": "^1.2.0",
-    "karma-mocha": "^1.3.0",
-    "karma-safari-launcher": "^1.0.0",
-    "mocha": "^2.3.2",
-    "prettier": "^2.2.1",
-    "rollup": "^1.13.1",
-    "rollup-plugin-commonjs": "^10.0.0",
-    "rollup-plugin-node-resolve": "^5.0.1",
-    "shelljs": "^0.8.4",
-    "should": "^7.1.1",
-    "watchify": "^3.11.1"
-  },
-  "dependencies": {
-    "@mparticle/web-sdk": "^2.12.8",
-    "isobject": "^4.0.0"
-  },
-  "license": "Apache-2.0"
+    "name": "@mparticle/web-amplitude-kit",
+    "version": "2.3.0",
+    "author": "mParticle Developers <developers@mparticle.com> (https://www.mparticle.com)",
+    "description": "mParticle integration sdk for Amplitude",
+    "main": "dist/Amplitude.common.js",
+    "files": [
+        "dist/Amplitude.common.js"
+    ],
+    "repository": "https://github.com/mparticle-integrations/mparticle-javascript-integration-amplitude",
+    "scripts": {
+        "build": "rollup --config rollup.config.js",
+        "build:test": "rollup --config rollup.test.config.js",
+        "test": "npm run build && npm run build:test && DEBUG=false karma start test/karma.config.js",
+        "test:debug": "npm run build && npm run build:test && DEBUG=true karma start test/karma.config.js",
+        "watch": "rollup --config rollup.config.js -w"
+    },
+    "devDependencies": {
+        "@mparticle/web-sdk": "^2.12.8",
+        "@semantic-release/changelog": "^5.0.1",
+        "@semantic-release/exec": "^5.0.0",
+        "@semantic-release/git": "^9.0.0",
+        "chai": "^4.2.0",
+        "eslint-config-prettier": "6.3.0",
+        "eslint-plugin-prettier": "3.1.1",
+        "karma": "^5.0.9",
+        "karma-chai": "^0.1.0",
+        "karma-chrome-launcher": "^2.2.0",
+        "karma-edge-launcher": "^0.4.2",
+        "karma-firefox-launcher": "^1.1.0",
+        "karma-ie-launcher": "^1.0.0",
+        "karma-junit-reporter": "^1.2.0",
+        "karma-mocha": "^1.3.0",
+        "karma-safari-launcher": "^1.0.0",
+        "mocha": "^2.3.2",
+        "prettier": "^2.2.1",
+        "rollup": "^1.13.1",
+        "rollup-plugin-commonjs": "^10.0.0",
+        "rollup-plugin-node-resolve": "^5.0.1",
+        "shelljs": "^0.8.4",
+        "should": "^7.1.1",
+        "watchify": "^3.11.1"
+    },
+    "license": "Apache-2.0"
 }

package/CHANGELOG.md

@@ -1,49 +0,0 @@
-## Releases
-
---
-#### 2.2.0 - 2021-11-03
-
--   feat: Support other5-other10 IDs
-
-#### 2.1.0 - 2021-08-30
-
--   feat: Add support for EU Data Center
-
-#### 2.0.8 - 2021-05-26
-
--   Generate bundle that was not included in 2.0.7 release 
-
-#### 2.0.7 - 2021-05-26
-
--   fix: Map impression and promotion events to align with server
-
-#### 2.0.6 - 2021-04-06
-
--   feat: Add includeEmailAsUserProperty and no longer set userIdentities as user properties to align with server
-
-    -   Previously the web kit set non-customerid user identities as user properties. This was not consistent with the server, and so this functionality has been removed from web SDK v2.
-
--   build: Update eslint/prettier config, fix linting errors
-
-#### 2.0.5 - 2021-01-11
-
--   Update Amplitude SDK to 7.2.1
--   Bugfix - Check window for node environments
--   Remove build file from root directory
-
-#### 2.0.4 - 2020-11-04
-
--   Bugfix - remove isTesting variable
-
-#### 2.0.3 - 2020-06-30
-
--   Feat: Support sending objects as custom attributes to Amplitude
-
-#### 2.0.2 - 2020-06-03
-
--   Update Amplitude SDK version to 6.2.0
--   Update test configuration
-
-#### 2.0.1 - 2020-02-03
-
--   Modify rollup settings - build dist files