README
Enhanced (e)Commerce plugin for GTM
EC is a plugin which provides functions to push Google Analytics Enhanced Ecommerce data into GTM in browser automatically using data in html markup.
This version can be installed by npm install --save @comsultia/enhanced-commerce.
Usage
In gulpfile.js add EC to your array of JS files, for example (or whatever you like):
// gulpfile.js
const jsFiles = [
path.src.js + 'vendor/jquery.slim.min.js',
path.src.js + 'vendor/popper.min.js',
path.src.js + 'vendor/bootstrap.min.js',
'node_modules/@comsultia/enhanced-commerce/dist/ec-plugin-bundle.js',
path.src.js + 'custom.js',
...
];
for more detailed gulp configuration, check gulpfile.js in 'node_modules/@comsultia/enhanced-commerce/gulpfile.js'
Add into .js or .html this initialization
<script>
ecService = ec.init({
'dataLayer': dataLayer, // optional
'prefix': 'data-ec', // default
'currencyCode': 'EUR', // optional
'debug': true // loggin into console (devel mode)
});
</script>
Setup GTM for Enhanced Ecommerce
EC is sending events into dataLayer[] as specified here: https://developers.google.com/tag-manager/enhanced-ecommerce. To work as specified, please add required tags and triggers into your Tag Manager.
Syntax
All data are marked in html code using data-ec-* attributes of elements. When required attributes not found, EC is searching missing attributes in closest elements. data-ec prefix can be changed in ec.init setup.
Created ecService object can be used to tracking in javascipt code.
Element's position
Works with all EC actions supported position attribute (impressions, follow, add, remove).
method a)
auto calculating position by siblings without defining data-ec-position:
<ul data-ec-list="Product list">
<li data-ec-id="1"
data-ec-name="name"
data-ec-action="view"
>
<span>Product 1 content</span>
</li>
<li data-ec-id="2"
data-ec-name="name"
data-ec-action="view"
>
<span>Product 2 content</span>
</li>
</ul>
method b)
- or you can override default behaviour with attribute
data-ec-position - helpful if you have to wrap element in sets of elements
- any nested HTML structure is allowed, EC will look for closest element with attribute
data-ec-position
<ul data-ec-list="Product list">
<li data-ec-position="1">
<div
data-ec-id="1"
data-ec-name="name"
data-ec-action="view"
>
<span>Product 1 content</span>
</div>
</li>
<li data-ec-position="2">
<div>
<div
data-ec-id="2"
data-ec-name="name"
data-ec-action="view"
>
<span>Product 2 content</span>
</div>
</div>
</li>
</ul>
Track product view
<ul data-ec-list="Homepage list">
<li data-ec-id="123"
data-ec-position="1"
data-ec-name="name"
data-ec-category="Items"
data-ec-brand="Brand"
data-ec-price="15.25"
data-ec-action="view"
data-ec-url="/product/123"
>
<span>product content</span>
</li>
</ul>
Grouped attributes in lists: in this example category and brand are the same in all products, and position is calculated by <li> position.
<ul data-ec-list="Homepage list"
data-ec-category="Items"
data-ec-brand="Brand"
>
<li data-ec-id="123"
data-ec-name="name"
data-ec-price="15.25"
data-ec-action="view"
>
<span>product content</span>
</li>
<li data-ec-id="124"
data-ec-name="name"
data-ec-price="15.25"
data-ec-action="view"
>
<span>product2 content</span>
</li>
</ul>
Track product view - on ajax response
If products are inserted into DOM on response (scroll, click or another event), you can call ecService method responseInit(limit) in your javascript functionality.
Simple example:
fetch(url)
.then(response => {
return response.json();
})
.then(html => {
html.map(product => {
$('.product-list').append(`
<li class="data-ec-item-response"
data-ec-id="123"
data-ec-position="1"
data-ec-name="name"
data-ec-category="Items"
data-ec-brand="Brand"
data-ec-price="15.25"
data-ec-action="view"
data-ec-url="/product/123">
>
{product.name}
</li>
`);
});
ecService.responseInit(limit);
}
- don't forget to add class attribute
data-ec-item-responseto inserted product item - don't forget to add
data-ec-action="view"attribute and alldata-ec...attributes limitparameter should represent number of inserted products (still updated after response and insertion success)
for more information, see example in index.html in 'node_modules/@comsultia/enhanced-commerce/dist/index.html'
Track product clicks
You can simply track clicks by adding data-ec-action="follow" into your code
<li data-ec-id="123">
<a href="/product-link" data-ec-action="follow">product link</a>
</li>
<li data-ec-id="124">
<a href="/product-link" data-ec-action="follow">product link</a>
</li>
or by using javascript funcion
<li data-ec-id="123">
<a href="#" onclick="ecService.follow(this)">product link</a>
</li>
Track product detail
You can simply track product detail view by adding data-ec-action="detail" and other data-ec-* attributes
<div data-ec-action="detail"
data-ec-id="123"
data-ec-name="Product name"
data-ec-category="Product category"
data-ec-brand="Brand"
data-ec-list="list"
data-ec-price="10.00"
data-ec-url="/product-name"
>
Product detail
</div>
Basket manipulation
Add product to cart provided by javascript
<li data-ec-id="125">
<a href="/product-link">
Product name
</a>
<span onclick="ecService.addCart(this,{quantity: 3})">
add to cart
</span>
</li>
You can override every information of product just by addCart method
ecService.addCart(event.srcElement,{
quantity: 3,
price: 12.25,
currency: 'EUR'
})
Remove product from cart
// when clicked on product element
ecService.removeCart(event.srcElement,{
quantity: 1
});
// or manipulation in cart
ecService.removeCart({
id: 123,
quantity: 1
})
Order process
Steps
method a)
Simply add to html data-ec-action with data-ec-step and data-ec-products attributes
<body
data-ec-action="step"
data-ec-step="1"
data-ec-products="
[{"id":"123","name":"Product 1 b","category":"Items","url":"/product-1","price":"10.00","quantity":"14"},
{"id":"124","name":"Product 2 b","url":"/product-2","price":"0.00","quantity":"1"},
{"id":"125","name":"Product 3 b","url":"/product-3","price":"0.25","quantity":"5"}]"
>...</body>
for more information, see example in cart-step-1.html in 'node_modules/@comsultia/enhanced-commerce/dist/cart-step-1.html'
method b)
or add class data-ec-track-cart-step to button/anchor with data-ec-step and data-ec-products attributes
<a
href="/cart-step-3.html"
class="data-ec-track-cart-step"
data-ec-step="2"
data-ec-products="
[{"id":"123","name":"Product 1 b","category":"Items","url":"/product-1","price":"10.00","quantity":"14"},
{"id":"124","name":"Product 2 b","url":"/product-2","price":"0.00","quantity":"1"},
{"id":"125","name":"Product 3 b","url":"/product-3","price":"0.25","quantity":"5"}]"
>
Next step
</a>
for more information, see example in cart-step-2.html in 'node_modules/@comsultia/enhanced-commerce/dist/cart-step-2.html'
method c)
or just call JS method steps(param1, param2, param3)
ecService.steps(3, ['billing 4', 'shipping 3'],
[
{id: "123", name: "Product 1 b", category: "Items", url: "/product-1", price: "10.00", quantity: "14"},
{id: "124", name: "Product 2 b", url: "/product-2", price: "0.00", quantity: "1"},
{id: "125", name: "Product 3 b", url: "/product-3", price: "0.25", quantity: "5"}
]
);
for more information, see example in cart-step-3.html in 'node_modules/@comsultia/enhanced-commerce/dist/cart-step-3.html'
Steps options
Add data-ec-option attribute to billing, shipping etc. inputs.
<h4>Shipping options</h4>
<div>
<input type="radio" name="shipping" id="shipping1" value="shipping1" data-ec-option>
<label for="shipping1">
shipping 1
</label>
</div>
<div class="form-check">
<input type="radio" name="shipping" id="shipping2" value="shipping2" data-ec-option>
<label class="form-check-label" for="shipping2">
shipping 2
</label>
</div>
Then add data-ec-track-cart-step to button/anchor with data-ec-step attribute (same as example method b)), javascript will looking for checked input and send it to Google Analytics as current step actionField or add second parameter as an array showed in example method c).
for more information, see example in cart-step-2.html in 'node_modules/@comsultia/enhanced-commerce/dist/cart-step-2.html'
Purchase
method a)
You are able to call javascript method purchase(param1, param2):
ecService.purchase(
{
id: "778",
affiliation: "Eshop - inline",
revenue: parseFloat(81.30).toFixed(2),
shipping: parseFloat(3.00).toFixed(2),
tax: parseFloat(13.05).toFixed(2)
},
[
{id: "123", name: "Product 1", category: "Items", url: "/product-1", price: "10.00", quantity: "10"},
{id: "124", name: "Product 2", url: "/product-2", price: "0.00", quantity: "1"},
{id: "125", name: "Product 3", url: "/prodcut-2", price: "0.25", quantity: "3"}
]
);
where first parameter is object with parameters:
(id: string, affiliation: string, revenue: number, shipping: number, tax: number)
and second parameter is array of objects
method b)
Add into html data-ec-action attribute with all purchase attributes data-ec-id, data-ec-affiliation, data-ec-revenue, data-ec-shipping, data-ec-tax and data-ec-products.
Then defined purchase actionField object details in html by attributes:
<body
data-ec-action="purchase"
data-ec-purchase-id="779"
data-ec-purchase-affiliation="Eshop"
data-ec-purchase-revenue="81.30"
data-ec-purchase-shipping="3.00"
data-ec-purchase-tax="13.05"
data-ec-products="
[{"id":"123","name":"Product 1 b","category":"Items","url":"/product-1","price":"10.00","quantity":"14"},
{"id":"124","name":"Product 2 b","url":"/product-2","price":"0.00","quantity":"1"},
{"id":"125","name":"Product 3 b","url":"/product-3","price":"0.25","quantity":"5"}]"
>
for more information, see example in cart-step-3.html in 'node_modules/@comsultia/enhanced-commerce/dist/cart-step-3.html'
Useful information
- you are able to define actions in
data-ec-actionattribute by:
data-ec-action="step, purchase-prepare"
- simply seperate actions by
, - spaces are trimmed
DEMO
- in 'node_modules/@comsultia/enhanced-commerce' open '/dist/index.html' in your browser and check browser console with all events logs