Enhanced ecommerce

[dominykas]

Starting a discussion sooner, rather than later... We (https://github.com/insidewarehouse) need to have enhanced ecommerce support and so we're going to build it, but I'd also like some input/agreement before we make a PR :)

Google's documentation:

• Intro
• Enhanced ecommerce via measurement protocol
• Enhanced ecommerce via analytics.js + ecommerce.js plugin

For the most of it, I think we might be able to just copy the ecommerce.js API, i.e. activities and impressions are usually trackable only with event and pageview hit types, so I think it's OK to just create addProduct, addImpression and setAction as methods. Discussion topics:

• Passing the currency (cu param) - normally it's set on the hit (i.e. via options event or pageview), but I have a feel it should go together with ecommerce data :)
• Should the 3 new methods live directly as public, or should there be some sort of a namespace? Opt-in in constructor? What if data is added, send() is called, but there are no actual hits set up to be sent?
• The protocol does allow to track some of the params with all hit types, so an alternative approach would be to add the ecommerce info to the options of the hit itself, e.g. impressionData, productData, actionData properties on the object.

The bigger problem is the transaction type. Documentation says that one should not be sending both - "regular" ecommerce and "enhanced" ecommerce requests (see "Important" section under "Overview"). Enhanced ecommerce also requires an explicit opt-in via admin/settings of the analytics property. Under the "regular" approach, multiple hits with item and one with transaction is sent. Under the enhanced - transaction data can be sent with any hit type, but it can also include "Product data" and "Action data" (with action type purchase I presume). The params for transaction data are the same, though. To summarize:

• Regular ecommerce sends a transaction hit with multiple optional item hits
• Enhanced ecommerce can send transaction related params (ID, amounts, currency) with any hit (e.g. pageview, event or transaction itself), but the products are sent as "product data" and also need an "action data" (with purchase action type, albeit there are other action types).

The two approaches are mutually exclusive. Discussion topics:

• Should there be an exclusive opt-in into "enhanced" ecommerce via constructor? When enhanced=true, the item hit should be disabled, otherwise - any "enhanced" data logging should be disabled.
• Should we just leave the decision on the consumer itself? The implementation would certainly be easier if all hit methods (event(), pageview(), etc) would just accept the ecommerce data and transform it into correct params (pr0cd0=Member for the custom dimension "0" of the first product) and not care about anything else.

I'll see if I can find out what other libraries in other languages do, but for now - just opening up the discussion.

[dominykas]

One more alternative would be to keep universal-analytics as a "raw", "close to the metal" library and send all the relevant ecommerce params via options object (use standard validation logic, with extensions in a similar way to custom dimensions implementation) and build a new library to construct these params...

[alessbell]

@dominykas Hi Dominykas! We (https://github.com/breather) need enhanced ecommerce support too. Let me know how I can help!

[dominykas]

PR #29 is ready - it updates the acceptable params and also the validations, however it must be noted, that the lib DOES support all the EE params, except that without my PR it will give warnings if debug flag is set to true.

I also published a gampee module to help with constructing EE params (I'll update and document it further), but here's some sample code how to use it:

var gampee = require("gampee"),
    ga = require("universal-analytics"),
    _ = require("lodash");

var ecommerceParams = gampee([
    {
        // visitor saw two products in search
        "type": "impression",
        "list": "search",
        "products": [
            { "id": "shirtM", "name": "Nice T-Shirt (M)", "position": 1 },
            { "id": "shirtXL", "name": "Nice T-Shirt (XL)", "position": 2 }
        ],
        "currency": "EUR"
    },
    {
        // visitor saw one product in highlights
        "type": "impression",
        "list": "highlights",
        "products": [
            { "id": "pants", "name": "Pretty Pants" }
        ],
        "currency": "EUR"
    },
    {
        // and added one 5 of shirtM to cart
        "type": "add",
        "products": [
            { "id": "shirtM", "name": "Nice T-Shirt (M)", "position": 1, "quantity": 5 }
        ],
        "currency": "EUR"
    }
]);

var ua = ga("UA-00000000-0", "5bbb81ff-0757-44e0-8fcb-f263d982b95a", { debug: true });
ua.pageview(_.merge({
    dp: "/",
    cd20: "one",
    cm20: "two"
}, ecommerceParams));

Result:

[universal-analytics] Enqueued pageview ({"dp":"/","cd20":"one","cm20":"two","il1nm":"search","cu":"EUR","il1pi1id":"shirtM","il1pi1nm":"Nice T-Shirt (M)","il1pi1ps":"1","il1pi2id":"shirtXL","il1pi2nm":"Nice T-Shirt (XL)","il1pi2ps":"2","il2nm":"highlights","il2pi1id":"pants","il2pi1nm":"Pretty Pants","pa":"add","pal":"search","pr1id":"shirtM","pr1nm":"Nice T-Shirt (M)","pr1ps":"1","pr1qt":"5","v":"1","tid":"UA-00000000-0","cid":"5bbb81ff-0757-44e0-8fcb-f263d982b95a","t":"pageview"})

[amit034]

tried this sample code got : [universal-analytics] Warning! Unsupported tracking parameter il1nm (search) [universal-analytics] Warning! Unsupported tracking parameter il1pi1id (shirtM) [universal-analytics] Warning! Unsupported tracking parameter il1pi1nm (Nice T-Shirt (M)) [universal-analytics] Warning! Unsupported tracking parameter il1pi1ps (1) [universal-analytics] Warning! Unsupported tracking parameter il1pi2id (shirtXL) [universal-analytics] Warning! Unsupported tracking parameter il1pi2nm (Nice T-Shirt (XL)) [universal-analytics] Warning! Unsupported tracking parameter il1pi2ps (2) [universal-analytics] Enqueued pageview ({"dp":"/search?q=some+product","cd20":"one","cm20":"two","il1nm":"search","cu":"EUR","il1pi1id":"shirtM","il1pi1nm":"Nice T-Shirt (M)","il1pi1ps":"1","il1pi2id":"shirtXL","il1pi2nm":"Nice T-Shirt (XL)","il1pi2ps":"2","v":"1","tid":"UA-62992924-1","cid":"5bbb81ff-0757-44e0-8fcb-f263d982b95a","t":"pageview"})

and no impression under conversation -> ecommerce -> overview

[dominykas]

The warnings are because the PR is still not merged.

As for impressions - just to double check - you know there's a delay until the stats display, right? Did the "add to cart" appear?